nc_diag_write_mod.F90

! nc_diag_write - NetCDF Layer Diag Writing Module
! Copyright 2015 Albert Huang - SSAI/NASA for NASA GSFC GMAO (610.1).
! 
! Licensed under the Apache License, Version 2.0 (the "License");
! you may not use this file except in compliance with the License.
! You may obtain a copy of the License at
! 
!   http://www.apache.org/licenses/LICENSE-2.0
! 
! Unless required by applicable law or agreed to in writing, software
! distributed under the License is distributed on an "AS IS" BASIS,
! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
! implied. See the License for the specific language governing
! permissions and limitations under the License.
! 
! Main module - nc_diag_write_mod
!

module nc_diag_write_mod
    ! Library that provides a high level interface for storing channel-
    ! based and observation-based data.
    ! 
    ! This library allows developers to easily store channel-based data
    ! (e.g. chaninfo) and observation-based data (metadata and data2d)
    ! to a NetCDF file via an easy to use API.
    ! 
    ! Internally, the process for storing this data looks like this:
    !   -> When the developer calls nc_diag_init, the NetCDF file is
    !      opened internally. The corresponding NCID is stored, and
    !      any memory allocation needed is done at this step.
    !      => If the file was opened in append mode, nc_diag_write will
    !         attempt to load any existing variable definitions for all
    !         types of variables - chaninfo, metadata, and data2d.
    !         Appropriate variable counters and data for each variable
    !         type will be set during init, and data writing will start
    !         at the end of the variable.
    !      
    !   -> Headers are essentially NetCDF global attributes, or
    !      attributes that describe a file. These can be added at any
    !      time during the writing session.
    !      
    !   -> varattr, or variable attributes, describe an associated
    !      variable. (This is a NetCDF4 variable attribute!) These can
    !      only be added after variable definitions have been locked.
    !      
    !   -> chaninfo variables:
    !      => nc_diag_chaninfo_dim_set must be called first to set
    !         the nchans dimension. If it isn't called, doing any
    !         chaninfo operation will result in an error.
    !      => chaninfo variables are 1D, with nchans number of elements.
    !      
    !   -> metadata and data2d variables:
    !      => metadata and data2d variables do not require any initial
    !         dimension setting - nc_diag_write will keep track of your
    !         number of observations for you!
    !      => metadata variables are 1D, with nobs number of elements.
    !         nobs can increase infinitely to fit the number of
    !         observations recorded.
    !      => data2d variables are 2D, with dimensions of nobs by
    !         another fixed dimension.
    !      
    !   -> Definition locking is sometimes necessary for certain
    !      operations, such as defining variable attributes. They are
    !      necessary due to needing information from NetCDF after
    !      variables are defined, or needing to assert that certain
    !      variable properties are constant. Locking uses the following
    !      steps:
    !      => nc_diag_*_write_def is called to send the variable
    !         definitions to NetCDF. This include defining any
    !         dimensions necessary, as well as defining the variables
    !         stored as well.
    !      => Once each nc_diag_*_write_def completes, their
    !         corresponding def_lock state will be set to TRUE, locking
    !         the definitions in place.
    !      => Attempts to make repeated calls will result in an error,
    !         due to the def_lock state being set to TRUE.
    !      
    !   -> Data calls will store the input data into memory. The
    !      implementation and design of the variable storage is
    !      dependent on the variable type being stored. chaninfo
    !      variables have a certain storage format, and metadata/data2d
    !      variables have another storage format. Note that metadata
    !      and data2d code have a few similarities in data storage
    !      since the variables themselves share common features, like
    !      the nobs dimension.
    !      
    !   -> Sometimes, there is a significant amount of data that needs
    !      to be processed and stored. Since nc_diag_write stores all
    !      of the data into memory (RAM) before it is written out,
    !      there may not be enough memory to store the entirety of the
    !      data. To alleviate that, nc_diag_flush_buffer can be called
    !      to flush the data from the memory and write them to disk.
    !      In reality, this doesn't actually free any memory... but the
    !      memory savings gained is still there. Calling the flushing
    !      subroutine performs the following steps:
    !      => It first checks to make sure that definitions are locked.
    !         The NetCDF variable IDs are needed in order to actually
    !         write (or "put") any data into the file.
    !      => It also checks to see if the data has already been locked.
    !         No more data can be written if the data has been locked.
    !      => It then calls all of the nc_diag_*_write_data subroutines
    !         with a special flag to indicate data flushing. When the
    !         data flushing flag is set, each of the variable
    !         subroutines will take measures to operate as a buffer
    !         flush, and not as a finalized data write.
    !      => When flushing within the variable subroutine, the
    !         subroutine first writes out any data using the variable-
    !         specific, memory-stored data.
    !      => It then resets any internal data counters that it may use
    !         to store and keep track of the data.
    !      => As mentioned before, it does not actually free any memory
    !         since deallocating and subsequently reallocating from
    !         scratch will take a long time, and is inefficient. With
    !         a counter reset, each variable type's internal data
    !         storage will start at the beginning of the data array,
    !         effectively avoiding any need to add any more memory, and
    !         thus achieving the goal of not using any more memory.
    !      => Finally, since the writing is in buffer flushing mode,
    !         the data_lock flag for each variable type is NOT set.
    !         This is so that more data can be written, either with
    !         the flushing method or with the regular write.
    !      
    !   -> Once data is done being queued ("stored"), nc_diag_write can
    !      be called. The variables will have their data re-read from
    !      memory and actually written to the file. This is also very
    !      much variable type independent, since every variable has its
    !      own way of storing variable data. Again, metadata and data2d
    !      have similar code, with the only difference being the
    !      dimensionality. Note that this is where NetCDF calls are
    !      made to define and "put" data. Once done, if we are NOT in
    !      append mode, we call nf90_enddef to end define mode.
    !      
    !   -> Once all the data has been queued and/or written out, it is 
    !      safe to call nc_diag_finish. We call this from nc_diag_write.
    !      => This will first write definitions and data, if applicable.
    !         The calls will have a special flag set to ensure that no
    !         errors are triggered for already having a lock set, since
    !         this subroutine will be closing the file anyways.
    !      => Once all of the data has been sent to NetCDF, this will
    !         tell NetCDF to close the file being written. Note that
    !         NetCDF also keeps a memory cache of the data being stored
    !         as well, so actual I/O writing may not be completely done
    !         until here. After the writing and closing on the NetCDF
    !         side completes, everything will be completely deallocated,
    !          and everything will be reset.
    !      
    !   -> Upon reset, nc_diag_write is again ready to write a new file
    !      via nc_diag_create!
    ! 
    ! Note that only ONE file is written as a time. This is due to the
    ! nature of the library focusing and storing data for a single
    ! file. Attempting to create another file without closing the
    ! previous one will result in an error.
    
    ! Load state variables! We need to know:
    !   init_done           - ...whether a file is currently loaded or
    !                         not.
    !   append_only         - ...whether we are in append mode or not.
    !   ncid                - ...the current NCID of our file.
    !   enable_trim         - ...whether we need to automatically trim
    !                         our strings for chaninfo string storage or
    !                         not.
    !   diag_chaninfo_store - ...chaninfo variable information.
    !                         Specifically, whether it's allocated or
    !                         not, and if it's allocated, whether the
    !                         definitions are locked or not. (def_lock)
    !   diag_metadata_store - ...metadata variable information.
    !                         Specifically, whether it's allocated or
    !                         not, and if it's allocated, whether the
    !                         definitions are locked or not. (def_lock)
    !   diag_data2d_store   - ...data2d variable information.
    !                         Specifically, whether it's allocated or
    !                         not, and if it's allocated, whether the
    !                         definitions are locked or not. (def_lock)
    use ncdw_state, only: init_done, append_only, ncid, &
        enable_trim, cur_nc_file, &
        diag_chaninfo_store, diag_metadata_store, diag_data2d_store, &
        diag_varattr_store
    
    ! Load needed NetCDF functions and constants
    use netcdf, only: nf90_inq_libvers, nf90_open, nf90_create, &
        nf90_enddef, nf90_close, nf90_sync, &
        NF90_WRITE, NF90_NETCDF4, NF90_CLOBBER
    
    !------------------------------------------------------------------
    ! API imports to expose API from this module
    ! (Plus general imports for this module as well!)
    !------------------------------------------------------------------
    
    ! Load necessary command line message subroutines and state
    ! variables
    use ncdw_climsg, only: &
#ifdef ENABLE_ACTION_MSGS
        nclayer_enable_action, nclayer_actionm, &
#endif
        nclayer_error, nclayer_warning, nclayer_info, nclayer_check, &
        nc_set_info_display, nc_set_action_display
    
    ! Load nc_diag_write specific types
    use ncdw_types, only: NLAYER_BYTE, NLAYER_SHORT, NLAYER_LONG, &
        NLAYER_FLOAT, NLAYER_DOUBLE, NLAYER_STRING
    
    ! Load header writing API
    use ncdw_lheader, only: nc_diag_header
    
    ! Load chaninfo writing API + auxillary functions for our use
    use ncdw_chaninfo, only: nc_diag_chaninfo_dim_set, &
        nc_diag_chaninfo, &
        nc_diag_chaninfo_load_def, nc_diag_chaninfo_write_def, &
        nc_diag_chaninfo_write_data, &
        nc_diag_chaninfo_set_strict, &
        nc_diag_chaninfo_allocmulti, nc_diag_chaninfo_prealloc_vars, &
        nc_diag_chaninfo_prealloc_vars_storage
    
    ! Load metadata writing API + auxillary functions for our use
    use ncdw_metadata, only: nc_diag_metadata, &
        nc_diag_metadata_load_def, nc_diag_metadata_write_def, &
        nc_diag_metadata_write_data, &
        nc_diag_metadata_set_strict, &
        nc_diag_metadata_allocmulti, &
        nc_diag_metadata_prealloc_vars, &
        nc_diag_metadata_prealloc_vars_storage, &
        nc_diag_metadata_prealloc_vars_storage_all, &
        nc_diag_metadata_to_single
    
    ! Load data2d writing API + auxillary functions for our use
    use ncdw_data2d, only: nc_diag_data2d, &
        nc_diag_data2d_load_def, nc_diag_data2d_write_def, &
        nc_diag_data2d_write_data, &
        nc_diag_data2d_set_strict, &
        nc_diag_data2d_allocmulti, &
        nc_diag_data2d_prealloc_vars, &
        nc_diag_data2d_prealloc_vars_storage, &
        nc_diag_data2d_prealloc_vars_storage_all
    
    ! Load varattr (variable attribute) writing API
    use ncdw_varattr, only: nc_diag_varattr
    
    implicit none
    
    contains
        ! Creates or appends to a new NetCDF file for data writing.
        ! 
        ! Given the target NetCDF file name, attempt to create or open
        ! the file and set everything up for writing data to the file.
        ! This includes any internal memory allocation required for
        ! buffering any data sent to this file.
        ! 
        ! If the file is opened in non-append mode (default), this will
        ! attempt to create a new file and start data writing from
        ! scratch. If the file already exists, it will be OVERWRITTEN
        ! without any prompt.
        ! 
        ! If the file is opened in append mode, this will attempt to
        ! open the file specified, read the file's dimension and
        ! variable storage information, and set things up so that
        ! data writing starts at the end of the file's existing data.
        ! Note that append mode only works for nc_diag_write NetCDF
        ! files. Attempting to open a non-nc_diag_write file could
        ! result in errors!
        ! 
        ! In order for the file to be written to successfully,
        ! nc_diag_finish MUST be called for all of the data to be
        ! flushed, and the corresponding memory to be freed.
        ! 
        ! nc_diag_write may only operate on one file at a time. This is
        ! due to the nature of nc_diag_write focusing on a single file.
        ! 
        ! If a NetCDF file is already open, this will raise an error
        ! and the program will terminate.
        ! 
        ! Args:
        !     filename (character(len=*)): NetCDF file name to create or
        !         append to.
        !     append (logical, optional): whether to open the NetCDF
        !         file in append mode or not. By default, if this is
        !         not specified, the file will be opened regularly (not
        !         in append mode).
        ! 
        ! Raises:
        !     If a file is already open, an error occurs and the program
        !     will exit.
        !     
        !     If the file specified does not exist, or there are issues
        !     with NetCDF creating/opening/using the file, an error
        !     will occur with the corresponding NetCDF error.
        !     
        !     Issues with storage allocation are bugs, and will also
        !     result in an error with an indication that a bug has
        !     occurred.
        ! 
        subroutine nc_diag_init(filename, append)
            character(len=*),intent(in)    :: filename
            logical, intent(in), optional  :: append
            
            ! Buffer size variable for NetCDF optimization settings
            ! (Not sure if this helps much...)
            integer                        :: bsize = 16777216;
            
#ifdef ENABLE_ACTION_MSGS
            character(len=1000)                   :: action_str
            
            if (nclayer_enable_action) then
                if (present(append)) then
                    write(action_str, "(A, L, A)") "nc_diag_init(filename = " // trim(filename) // &
                        ", append = ", append, ")"
                else
                    write(action_str, "(A)") "nc_diag_init(filename = " // trim(filename) // &
                        ", append = (not specified))"
                end if
                call nclayer_actionm(trim(action_str))
            end if
#endif
            
            ! Inform user about NetCDF version
            call nclayer_info('Initializing netcdf layer library, version ' // trim(nf90_inq_libvers()) // '...')
            
            ! Make sure we haven't initialized yet. If we have, it
            ! means that another file is open that hasn't been closed
            ! yet!
            if (.NOT. init_done) then
                ! Special append mode - that means that we need to
                ! assume that all definitions are set and locked.
                if (present(append) .AND. (append .eqv. .TRUE.)) then
                    ! Open the file in append mode!
                    call nclayer_check( nf90_open(filename, NF90_WRITE, ncid, &
                        bsize, cache_nelems = 16777216) ) ! Optimization settings
                    
                    ! Set the append flag
                    append_only = .TRUE.
                else
                    ! Create the file from scratch!
                    
                    ! nf90_create creates the NetCDF file, and initializes
                    ! everything needed to write a NetCDF file.
                    ! 
                    ! NF90_CLOBBER forces overwriting the file, even if it already
                    ! exists.
                    ! 
                    ! ncid is a special ID that the NetCDF library uses to keep
                    ! track of what file you're working on. We're returning that
                    ! here.
                    call nclayer_check( nf90_create(filename, OR(NF90_NETCDF4, NF90_CLOBBER), ncid, &
                        0, bsize, cache_nelems = 16777216) ) ! Optimization settings
                end if
                
                ! Allocation sanity checks...
                ! These storage variables should NOT be allocated.
                ! If they are, it indicate that we have a serious problem.
                if (allocated(diag_chaninfo_store)) then
                    call nclayer_error("BUG! diag_chaninfo_store is allocated, but init_done is not set!")
                end if
                
                if (allocated(diag_metadata_store)) then
                    call nclayer_error("BUG! diag_metadata_store is allocated, but init_done is not set!")
                end if
                
                if (allocated(diag_data2d_store)) then
                    call nclayer_error("BUG! diag_data2d_store is allocated, but init_done is not set!")
                end if
                
                if (allocated(diag_varattr_store)) then
                    call nclayer_error("BUG! diag_data2d_store is allocated, but init_done is not set!")
                end if
                
                ! All good, allocate the storage variables!
                allocate(diag_chaninfo_store)
                allocate(diag_metadata_store)
                allocate(diag_data2d_store)
                allocate(diag_varattr_store)
                
                ! Set the current file being written to...
                cur_nc_file = filename
                
                ! Set the flag state to indicate that a file is open,
                ! and that initialization is done.
                init_done = .TRUE.
                
                ! "Lock and load" the definitions... or simply ask
                ! chaninfo/metadata/data2d to read the NetCDF files,
                ! build a cache, and set up anything necessary to be
                ! able to resume writing from before.
                if (present(append) .AND. (append .eqv. .TRUE.)) then
                    call nclayer_info("Loading chaninfo variables/dimensions from file:")
                    call nc_diag_chaninfo_load_def
                    
                    call nclayer_info("Loading metadata variables/dimensions from file:")
                    call nc_diag_metadata_load_def
                    
                    call nclayer_info("Loading data2d variables/dimensions from file:")
                    call nc_diag_data2d_load_def
                end if
            else
                ! Opening a new file while another file is still open is
                ! bad... let's yell at the user/developer!
                call nclayer_error("Attempted to initialize without closing previous nc_diag file!" &
                    // char(10) &
                    // "             (Previous file: " // trim(cur_nc_file) &
                    // char(10) &
                    // "              Attempted to open file: " // trim(filename) // ")")
            end if
        end subroutine nc_diag_init
        
        ! Lock and commit the variable definitions for the current
        ! NetCDF file.
        ! 
        ! Attempt to commit the currently stored variable definitions
        ! to the NetCDF file via NetCDF API calls. Once done, this will
        ! set the flag for locking the variable definitions, preventing
        ! any additional variables from being created or changed.
        ! 
        ! Locking the definitions here will enable functions that
        ! require variable definition locking. This include
        ! nc_diag_varattr and nc_diag_flush_buffer, both of which
        ! require the variable definitions to be committed and locked.
        ! 
        ! Definitions may not be locked more than once. In addition,
        ! creating new variables after definitions are locked will
        ! result in errors.
        ! 
        ! Args:
        !     None
        ! 
        ! Raises:
        !     The following errors will trigger indirectly from other
        !     subroutines called here:
        !     
        !     If definitions have already been locked, this will result
        !     in an error.
        !     
        !     If there is no file open, this will result in an error.
        !     
        !     Other errors may result from invalid data storage, NetCDF
        !     errors, or even a bug. See the called subroutines'
        !     documentation for details.
        ! 
        subroutine nc_diag_lock_def
#ifdef ENABLE_ACTION_MSGS
            if (nclayer_enable_action) then
                call nclayer_actionm("nc_diag_lock_def()")
            end if
#endif
            call nclayer_info("Locking all variable definitions!")
            
            ! Call all of the variable write_def
            call nclayer_info("Defining chaninfo:")
            call nc_diag_chaninfo_write_def
            
            call nclayer_info("Defining metadata:")
            call nc_diag_metadata_write_def
            
            call nclayer_info("Defining data2d:")
            call nc_diag_data2d_write_def
            
            call nclayer_info("All variable definitions locked!")
        end subroutine nc_diag_lock_def
        
        ! Write all of the variables to the NetCDF file, including the
        ! variable definitions and data, and close the file.
        ! 
        ! Attempt to write the currently stored variable definitions
        ! and data to the NetCDF file via NetCDF API calls.
        ! 
        ! Once done, this will lock both the definitions and the data,
        ! preventing any new variables or new data from being written
        ! after this call completes.
        ! 
        ! Once data has been written and locked, the file itself will be
        ! closed. NetCDF may internally cache/buffer variable data in
        ! memory, so actual writing may occur at this time to let NetCDF
        ! actually commit the data to disk.
        ! 
        ! Finally, nc_diag_write state cleanup and memory deallocation
        ! will occur via a call to nc_diag_finish.
        ! 
        ! Writing may not occur more than once. In addition, writing any
        ! new variables or adding any new data will result in an error.
        ! (Not that you can write any more data after this, since the
        ! file is closed and everything is reset...)
        ! 
        ! Args:
        !     None
        ! 
        ! Raises:
        !     The following errors will trigger indirectly from other
        !     subroutines called here:
        !     
        !     If the variable definitions have already been locked, this
        !     will NOT result in an error. This is due to the fact that
        !     we could've locked definitions earlier, and that we
        !     can assume that with locked definitions, we are able to
        !     write data.
        !     
        !     Data writing is the critical part. If the variable data
        !     writing has already been locked, this will result in an
        !     error.
        !     
        !     If there is no file open (or the file is already closed),
        !     this will result in an error.
        !     
        !     Other errors may result from invalid data storage, NetCDF
        !     errors, or even a bug. See the called subroutines'
        !     documentation for details.
        ! 
        subroutine nc_diag_write
#ifdef ENABLE_ACTION_MSGS
            if (nclayer_enable_action) then
                call nclayer_actionm("nc_diag_write()")
            end if
#endif
            
            ! Call all variable write_def, with an extra option to make
            ! sure that no errors occur during write, even when locked!
            ! (We could have previously locked, but here we're doing it
            ! on purpose!)
            call nclayer_info("Defining chaninfo:")
            call nc_diag_chaninfo_write_def(.TRUE.)
            
            call nclayer_info("Defining metadata:")
            call nc_diag_metadata_write_def(.TRUE.)
            
            call nclayer_info("Defining data2d:")
            call nc_diag_data2d_write_def(.TRUE.)
            
            ! Lock definition writing!
            if ((.NOT. append_only) .AND. ((.NOT. diag_chaninfo_store%def_lock) .OR. &
                (.NOT. diag_metadata_store%def_lock) .OR. &
                (.NOT. diag_data2d_store%def_lock))) &
                call nclayer_check(nf90_enddef(ncid))
            
            ! Call all variable write_data
            call nclayer_info("Writing chaninfo:")
            call nc_diag_chaninfo_write_data
            
            call nclayer_info("Writing metadata:")
            call nc_diag_metadata_write_data
            
            call nclayer_info("Writing data2d:")
            call nc_diag_data2d_write_data
            
            ! Call nf90_close to save everything to disk!
            call nclayer_info("All done queuing in data, letting NetCDF take over!")
            call nclayer_check(nf90_close(ncid))
            
            call nclayer_info("All done!")
            
            ! Call our cleanup subroutine
            call nc_diag_finish
        end subroutine nc_diag_write
        
        ! Reset nc_diag_write state, and deallocate all of the variable
        ! storage in preparation for another new NetCDF file write.
        ! 
        ! Attempt to reset nc_diag_write state and deallocate all of 
        ! the variable storage. This frees up memory, and allows for
        ! nc_diag_init to work again for a new file.
        ! 
        ! This can only be called once per open. (You can't call this
        ! without a nc_diag_init happening before it!) Calling this
        ! without any file opened (or data stored) will result in an
        ! error.
        ! 
        ! This is an internal subroutine, and is NOT meant to be called
        ! outside of nc_diag_write. Calling this subroutine in your
        ! program may result in unexpected behavior and/or data
        ! corruption!
        ! 
        ! Args:
        !     None
        ! 
        ! Raises:
        !     If there is no file open, or if no data/state needs to be
        !     cleaned up, this will result in an error.
        !     
        !     Issues with storage deallocation are bugs, and will also
        !     result in an error with an indication that a bug has
        !     occurred.
        ! 
        subroutine nc_diag_finish
#ifdef ENABLE_ACTION_MSGS
            if (nclayer_enable_action) then
                call nclayer_actionm("nc_diag_finish()")
            end if
#endif
            ! Make sure that we only deallocate if we have something
            ! open/initialized!
            if (init_done) then
                call nclayer_info("Cleaning up...")
                
                ! Do some quick sanity checks!
                if (.NOT. allocated(diag_chaninfo_store)) then
                    call nclayer_error("BUG! diag_chaninfo_store is not allocated, but init_done is set!")
                end if
                
                if (.NOT. allocated(diag_metadata_store)) then
                    call nclayer_error("BUG! diag_metadata_store is not allocated, but init_done is set!")
                end if
                
                if (.NOT. allocated(diag_data2d_store)) then
                    call nclayer_error("BUG! diag_data2d_store is not allocated, but init_done is set!")
                end if
                
                if (.NOT. allocated(diag_varattr_store)) then
                    call nclayer_error("BUG! diag_data2d_store is not allocated, but init_done is set!")
                end if
                
                ! Deallocate everything! Note that this deallocates
                ! everything within the derived type as well.
                ! (See? Fortran is better than C!)
                deallocate(diag_chaninfo_store)
                deallocate(diag_metadata_store)
                deallocate(diag_data2d_store)
                deallocate(diag_varattr_store)
                
                ! Clear initialization, append, and current file name
                ! state.
                init_done = .FALSE.
                append_only = .FALSE.
                cur_nc_file = ""
            else
                call nclayer_error("Attempted to deallocate without initializing!")
            end if
        end subroutine nc_diag_finish
        
        ! Flush all of the current variable data to NetCDF, and reset
        ! all of the variable storage to an initial state.
        ! 
        ! Attempt to write the currently stored variable definitions
        ! and data to the NetCDF file via NetCDF API calls.
        ! 
        ! Once done, this will effectively "flush" the data from the
        ! current variable buffers. Internally, this sets a starting
        ! counter and resets the buffer counter so that new data can
        ! be stored sequentially without requiring more memory, at least
        ! until memory runs out for the current buffer.
        ! 
        ! Definitions MUST be locked in order for flushing to work.
        ! Without definition locking, nc_diag_write is unable to make
        ! calls to NetCDF due to the lack of variable IDs.
        ! 
        ! If definitions are not locked, calling this will result in an
        ! error.
        ! 
        ! Data locking does NOT occur with flushing. As a result, this
        ! subroutine may be called multiple times, and a final
        ! nc_diag_write can be called once after this call.
        ! 
        ! (Note that calling nc_diag_write will lock the data and close
        ! the file, regardless of flushing the buffer here!)
        ! 
        ! Args:
        !     None
        ! 
        ! Raises:
        !     If definitions have not been locked, this will result in
        !     an error.
        !     
        !     The following errors will trigger indirectly from other
        !     subroutines called here:
        !     
        !     If the variable data writing has already been locked, this
        !     will result in an error.
        !     
        !     If there is no file open (or the file is already closed),
        !     this will result in an error.
        !     
        !     Other errors may result from invalid data storage, NetCDF
        !     errors, or even a bug. See the called subroutines'
        !     documentation for details.
        ! 
        subroutine nc_diag_flush_buffer
#ifdef ENABLE_ACTION_MSGS
            if (nclayer_enable_action) then
                call nclayer_actionm("nc_diag_flush_buffer()")
            end if
#endif
            if (.NOT. init_done) &
                call nclayer_error("Attempted to flush nc_diag_write buffers without initializing!")
            
            if ((.NOT. diag_chaninfo_store%def_lock) .OR. &
                (.NOT. diag_metadata_store%def_lock) .OR. &
                (.NOT. diag_data2d_store%def_lock)) &
                call nclayer_error("Definitions must be locked in order to flush the buffer!")
            
            ! Perform writes with the buffer flag set!
            call nclayer_info("Flushing chaninfo:")
            call nc_diag_chaninfo_write_data(.TRUE.)
            
            call nclayer_info("Flushing metadata:")
            call nc_diag_metadata_write_data(.TRUE.)
            
            call nclayer_info("Flushing data2d:")
            call nc_diag_data2d_write_data(.TRUE.)
            
            call nclayer_info("Flushing done!")
        end subroutine nc_diag_flush_buffer
        
        ! Force NetCDF to flush its buffers and write any data stored to
        ! disk.
        ! 
        ! Attempt to force the write of NetCDF's stored variable data to
        ! the NetCDF file via NetCDF API calls.
        ! 
        ! This does NOT flush nc_diag_write's buffers. It only attempts
        ! to flush NetCDF's internal buffers to disk.
        ! 
        ! If there is no file open, or the file is already closed, this
        ! will result in an error.
        ! 
        ! Args:
        !     None
        ! 
        ! Raises:
        !     If there is no file open (or the file is already closed),
        !     this will result in an error.
        !     
        !     Other errors may result from NetCDF errors. Any errors
        !     from NetCDF are likely to occur if there are problems
        !     writing to disk. Errors resulting from problems with
        !     manipulating NetCDF memory or a glitch are unlikely, but
        !     still possible.
        ! 
        subroutine nc_diag_flush_to_file
#ifdef ENABLE_ACTION_MSGS
            if (nclayer_enable_action) then
                call nclayer_actionm("nc_diag_flush_to_file()")
            end if
#endif
            ! Make sure we have something open + initialized
            if (.NOT. init_done) &
                call nclayer_error("Attempted to flush NetCDF buffers without initializing!")
            
            ! Call nf90_sync to try and commit the put'd data to disk
            call nclayer_check(nf90_sync(ncid))
        end subroutine nc_diag_flush_to_file
        
        ! Toggle whether nc_diag_write should be strict about dimensions
        ! and variable consistency.
        ! 
        ! Set the strictness of nc_diag_write for checking dimensions
        ! and stored variable consistency.
        ! 
        ! If set to TRUE, nc_diag_write will error when consistency
        ! checks fail.
        ! 
        ! If set to FALSE, nc_diag_write will only display a warning
        ! when these checks fail.
        ! 
        ! To see more details about what checks are made, see the
        ! corresponding called subroutine documentation for details.
        ! 
        ! Args:
        !     enable_strict (logical): whether to be strict with
        !         consistency checks or not.
        ! 
        ! Raises:
        !     If there is no file open (or the file is already closed),
        !     this will result in an error.
        !     
        !     Although unlikely, other errors may indirectly occur.
        !     They may be general storage errors, or even a bug.
        !     See the called subroutines' documentation for details.
        ! 
        subroutine nc_diag_set_strict(enable_strict)
            logical, intent(in) :: enable_strict
            
            ! Make sure we have something open + initialized
            if (init_done) then
                ! Call all of the variable set_strict subroutines
                call nc_diag_chaninfo_set_strict(enable_strict)
                call nc_diag_metadata_set_strict(enable_strict)
                call nc_diag_data2d_set_strict(enable_strict)
            else
                call nclayer_error("Can't set strictness level - NetCDF4 layer not initialized yet!")
            end if
        end subroutine nc_diag_set_strict
        
        ! Toggle whether nc_diag_write should trim strings or keep their
        ! original length.
        ! 
        ! Set the option to trim strings automatically with string
        ! variable data or not.
        ! 
        ! If set to TRUE, nc_diag_write will automatically trim strings
        ! to the minimum needed to hold the string. (Extra spaces at
        ! the end will be trimmed off the largest string in an array,
        ! and the result will be the bounds for that string array!)
        ! 
        ! If set to FALSE, nc_diag_write will NOT trim any strings. The
        ! given string length is assumed to be the bounds for holding
        ! the string. However, nc_diag_write will enforce strict
        ! checking of the input string length. If the length of the
        ! string changes during subsequent storage, nc_diag_write
        ! will error.
        ! 
        ! Note that this only applies to variable string storage.
        ! Attribute string storage is handled directly by NetCDF.
        ! From testing, it seems that NetCDF will trim your string when
        ! storing headers (global attributes).
        ! 
        ! Args:
        !     do_trim (logical): whether to automatically trim the
        !         stored strings or not.
        ! 
        ! Raises:
        !     Nothing... at least here. See above for potential errors
        !     outside of this subroutine.
        ! 
        subroutine nc_diag_set_trim(do_trim)
            logical, intent(in) :: do_trim
            
            enable_trim = do_trim
        end subroutine nc_diag_set_trim
end module nc_diag_write_mod