******************
Library Reference
******************

The ARM Data Integrator (ADI) provides a library of functions to access and manipulate the data stored in ADI's internal data structures.  These functions are provided in three languages:

- `C Reference`_
- `IDL Reference`_
- `Python Reference`_

============
C Reference
============

The full C reference library is `maintained here <https://engineering.arm.gov/~ermold/docs/doxygen/libdsproc3/html/>`_.

Datasets
========

=================  ===============================================================================================
**const char** \*  `dsproc_dataset_name`_ (CDSGroup \* *dataset*)   
                    Returns the dataset name.
                 
**CDSGroup** \*    `dsproc_get_output_dataset`_ (CDSgroup \* *dataset*)
                    Get an output dataset.
                 
**CDSGroup** \*    `dsproc_get_retrieved_dataset`_ (int *ds_id*, int *obs_index*)
                    Get a retreived dataset.
                 
**CDSGroup** \*    `dsproc_get_transformed_dataset`_ (const char \* *coordsys_name*, int *ds_id*, int *obs_index*)
                    Get a transformed dataset.
=================  ===============================================================================================

Dataset Dimensions
==================

=============  =================================================================================
**CDSDim** \*  `dsproc_get_dim`_ (CDSGroup \*dataset, const char \*name)
                Get a dimension from a dataset.

**size_t** \*  `dsproc_get_dim_legth`_ (CDSGroup \*dataset, const char \*name)
                Get the length of a dimension in a dataset.

**int**        `dsproc_set_dim_length`_ (CDSGroup \*dataset, const char \*name, size_t length)
                Set the length of a dimension in a dataset.
=============  =================================================================================

Dataset Attributes
==================

=============  ===================================================================================================================== 
**int**        `dsproc_change_att`_ (void \*parent, int overwrite, const char \*name, CDSDataType type, size_t length, void \*value)
                Change an attribute for a dataset or variable.

**CDSAtt** \*  `dsproc_get_att`_ (void \*parent, const char \*name)
                Get an attribute from a dataset or variable.

**char** \*    `dsproc_get_att_text`_ (void \*parent, const char \*name, size_t \*length, char \*value)
                Get a copy of an attribute value from a dataset or variable.

**void** \*    `dsproc_get_att_value`_ (void \*parent, const char \*name, CDSDataType type, size_t \*length, void \*value)
                Get a copy of an attribute value from a dataset or variable.

**int** \*     `dsproc_set_att`_ (void \*parent, int overwrite, const char \*name, CDSDataType type, size_t length, void \*value)
                Set the value of an attribute in a dataset or variable. 

**int** \*     `dsproc_set_att_text`_ (void \*parent, const char \*name, const char \*format,...)
                Set the value of an attribute in a dataset or variable.

**int** \*     `dsproc_set_att_value`_ (void \*parent, const char \*name, CDSDataType type, size_t length, void \*value)
                Set the value of an attribute in a dataset or variable.
=============  =====================================================================================================================

Dataset Variables
=================

=====================  ========================================================================================================================================================================================================================================================================

**CDSVar** \*          `dsproc_clone_var`_ (CDSVar \*src_var, CDSGroup \*dataset, const char \*var_name, CDSDataType data_type, const char \*\*dim_names, int copy_data)
                        Create a clone of an existing variable. 

**CDSVar**\_\*         `dsproc_define_var`_ (CDSGroup \*dataset, const char \*name, CDSDataType type, int ndims, const char \*\*dim_names, const char \*long_name, const char \*standard_name, const char \*units, void \*valid_min, void \*valid_max, void \*missing_value, void \*fill_value)
                        Define a new variable in an existing dataset.

**int**                `dsproc_delete_var`_ (CDSVar \*var)
                        Delete a variable from a dataset.

**CDSVar** \*          `dsproc_get_coord_var`_ (CDSVar \*var, int dim_index)
                        Get the coordinate variable for a variable's dimension.

**int**                `dsproc_get_dataset_vars`_ (CDSGroup \*dataset, const char \*\*var_names, int required, CDSVar \*\*\*vars, CDSVar \*\*\*qc_vars, CDSVar \*\*\*aqc_vars)
                        Get variables and companion QC variables from a dataset.

**CDSVar** \*          `dsproc_get_output_var`_ (int ds_id, const char \*var_name, int obs_index)
                        Get a variable from an output dataset.

**CDSVar** \*          `dsproc_get_qc_var`_ (CDSVar \*var)
                        Get the companion QC variable for a variable.

**CDSVar** \*          `dsproc_get_retrieved_var`_ (const char \*var_name, int obs_index)
                        Get a primary variable from the retrieved data.    

**CDSVar** \*          `dsproc_get_transformed_var`_ (const char \*var_name, int obs_index)
                        Get a primary variable from the transformed data.

**CDSVar** \*          `dsproc_get_trans_coordsys_var`_ (const char \*coordsys_name, const char \*var_name, int obs_index)
                        Get a variable from a transformation coordinate system.

**CDSVar** \*          `dsproc_get_var`_ (CDSGroup \*dataset, const char \*name)
                        Get a variable from a dataset.

**const char** \*      `dsproc_var_name`_ (CDSVar \*var)
                        Returns the variable name.

**size_t** \*          `dsproc_var_sample_count`_ (CDSVar \*var)
                        Returns the number of samples in a variable's data array.

**size_t** \*          `dsproc_var_sample_size`_ (CDSVar \*var)
                        Returns the sample size of a variable.
=====================  ========================================================================================================================================================================================================================================================================

Dataset Variable Data
=====================

===========  ======================================================================================================================================
**void** \*  `dsproc_alloc_var_data`_ (CDSVar \*var, size_t sample_start, size_t sample_count)
              Allocate memory for a variable's data array.
      
**void** \*  `dsproc_alloc_var_data_index`_ (CDSVar \*var, size_t sample_start, size_t sample_count)
              Allocate memory for a variable's data array. 

**void** \*  `dsproc_get_var_data_index`_ (CDSVar \*var)
              Get a data index for a multi-dimensional variable.

**void** \*  `dsproc_get_var_data`_ (CDSVar \*var, CDSDataType type, size_t sample_start, size_t \*sample_count, void \*missing_value, void \*data)
              Get a copy of the data from a dataset variable.

**int**      `dsproc_get_var_missing_values`_ (CDSVar \*var, void \*\*values)
              Get the missing values for a CDS Variable.

**void** \*  `dsproc_init_var_data`_ (CDSVar \*var, size_t sample_start, size_t sample_count, int use_missing)
              Initialize the data values for a dataset variable.

**void** \*  `dsproc_init_var_data_index`_ (CDSVar \*var, size_t sample_start, size_t sample_count, int use_missing)
              Initialize the data values for a dataset variable. 

**void** \*  `dsproc_set_var_data`_ (CDSVar \*var, CDSDataType type, size_t sample_start, size_t sample_count, void \*missing_value, void \*data)
              Set the data values for a dataset variable. 
===========  ======================================================================================================================================

Dataset Time Data
=================

================  ============================================================================================================================
**time_t**        `dsproc_get_base_time`_ (void \*cds_object)
                   Get the base time of a dataset or time variable.

**size_t**        `dsproc_get_time_range`_ (void \*cds_object, timeval_t \*start_time, timeval_t \*end_time)
                   Get the time range of a dataset or time variable.

**CDSVar** \*     `dsproc_get_time_var`_ (void \*cds_object)
                   Get the time variable used by a dataset.

**time_t** \*     `dsproc_get_sample_times`_ (void \*cds_object, size_t sample_start, size_t \*sample_count, time_t 
                   Get the sample times for a dataset or time variable.

**timeval_t** \*  `dsproc_get_sample_timevals`_ (void \*cds_object, size_t sample_start, size_t \*sample_count, timeval_t \*sample_times)
                   Get the sample times for a dataset or time variable.

**int**           `dsproc_set_base_time`_ (void \*cds_object, const char \*long_name, time_t base_time)
                   Set the base time of a dataset or time variable.

**int**           `dsproc_set_sample_times`_ (void \*cds_object, size_t sample_start, size_t sample_count, time_t \*sample_times)
                   Set the sample times for a dataset or time variable. 

**int**           `dsproc_set_sample_timevals`_ (void \*cds_object, size_t sample_start, size_t sample_count, timeval_t \*sample_times)
                   Set the sample times for a dataset or time variable.

================  ============================================================================================================================

Variable Tags
=============

Data Structures
---------------

==========  ==============================
**struct**  `VarTarget`_
               Output Variable Target.
==========  ==============================

Macros
------

============  ====================================================================
**\#define**  `VAR_SKIP_TRANSFORM`_ 0x1
                 Flag instructing the transform logic to ignore this variable.
============  ====================================================================

Functions
---------

========  ===================================================================================
**int**   `dsproc_add_var_output_target`_ (CDSVar \*var, int ds_id, const char \*var_name)
           Add an output target for a variable.

**int**   `dsproc_copy_var_tag`_ (CDSVar \*src_var, CDSVar \*dest_var)
           Copy a variable tag from one variable to another.

**void**  `dsproc_delete_var_tag`_ (CDSVar \*var)
           Delete a variable tag.

**int**   `dsproc_get_var_output_targets`_ (CDSVar \*var, VarTarget \*\*\*targets)
           Get the output targets defined for the specified variable.

**int**   `dsproc_set_var_coordsys_name`_ (CDSVar \*var, const char \*coordsys_name)
           Set the coordinate system for a variable.

**int**   `dsproc_set_var_flags`_ (CDSVar \*var, int flags)
           Set the control flags for a variable.

**int**   `dsproc_set_var_output_target`_ (CDSVar \*var, int ds_id, const char \*var_name)
           Set the output target for a variable.

**void**  `dsproc_unset_var_flags`_ (CDSVar \*var, int flags)
           Unset the control flags for a variable.

========  ===================================================================================

Variable DQRs
=============

Data Structures
---------------

==========  =============
**struct**  `varDQR`_
             Variable DQR
==========  =============

Functions
---------

=======  ======================================================================
**int**  `dsproc_get_var_dqrs`_ (CDSVar \*var, VarDQR \*\*\*dqrs)
          Get all available DQRs for the data stored in the specified variable.
=======  ======================================================================

Print Functions
===============

=======  =======================================================================================================================================
**int**  `dsproc_dump_dataset`_ (CDSGroup \*dataset, const char \*outdir, const char \*prefix, time_t file_time, const char \*suffix, int flags)
          Dump the contents of a dataset to a text file.

**int**  `dsproc_dump_output_datasets`_ (const char \*outdir, const char \*suffix, int flags)
          Dump all output datasets to text files.

**int**  `dsproc_dump_retrieved_datasets`_ (const char \*outdir, const char \*suffix, int flags)
          Dump all retrieved datasets to a text file.

**int**  `dsproc_dump_transformed_datasets`_ (const char \*outdir, const char \*suffix, int flags)
          Dump all transformed datasets to a text file.
=======  =======================================================================================================================================


==============
IDL Reference
==============

The `IDL code reference library is here <https://engineering.arm.gov/idl_docs/>`_. 



=================
Python Reference
=================

The `Python code reference library is here <https://engineering.arm.gov/py_lib_docs/>`_.