
######################
A3DAsmModelFileGetUnit
######################

.. c:function:: A3DStatus A3DAsmModelFileGetUnit(const A3DAsmModelFile *pModelFile, A3DDouble *pdUnit)

   .. rst-class:: sig-pretty-signature
   
      | :c:enum:`~A3DStatus` A3DAsmModelFileGetUnit(*const* :c:type:`~A3DAsmModelFile`\ \* **pModelFile**\ , :c:type:`~A3DDouble`\ \* **pdUnit**\ )
   
   Retrieves the unit a model file should be displayed with.
   
   
      12.0
   
   
   **Return Values**
   
   
      **A3D_SUCCESS**\ : if ``pModelFile`` is zero or if a unit is found.
   
      **A3D_INITIALIZE_NOT_CALLED**\ : if the library is not initialized.
   
      **A3D_INVALID_DATA_NULL**\ : if ``pdUnit`` is zero while ``pModelFile`` is nonzero.
   
      **A3D_ERROR**\ : if no unit is found.
   
   
   .. rubric:: Behavior
   
   
   When ``A3DAsmModelFileGetUnit`` finds a suitable unit in the provided model file, ``pdUnit`` is filled with a floating-point decimal representation of this unit, as stated in
   
   
   ::
   
      embed:rst:inline :doc:`/guide/units`
   
   . ``pdUnit`` can then be converted into :c:enum:`~A3DEUnits` using :c:func:`~A3DUnitGetFromEnum`\ .
   
   The unit of an entire model file depends on the value of the ``m_bUnitFromCAD`` field, either in :c:struct:`~A3DAsmModelFileData` or :c:struct:`~A3DAsmProductOccurrenceData`\ .
   
   ``A3DAsmModelFileGetUnit`` recursively traverses the model file given by ``pModelFile`` and stops on the first entity (model file or product occurrence) where ``m_bUnitFromCAD`` is *A3D_TRUE*\ . The ``m_dUnit`` field of this entity is then written in ``pdUnit``\ .
   
   
   - If ``pdUnit`` is *0*\ , the function returns ``A3D_INVALID_DATA_NULL``
   - \ If ``pModelFile`` is *0*\ , the function returns ``A3D_SUCCESS`` and ``*pdUnit`` is set to *0.0*\ .
   
   The traversal may complete without finding any unit. In this case, the function returns ``A3D_ERROR``\ .
   
   .. rubric:: Memory Management
   
   
   The caller is reponsible from the memory pointed to by ``pdUnit``\ .
   
   
   
      ::
   
         embed:rst:inline :doc:`/guide/units`
   
      , :c:func:`~A3DUnitGetFromEnum`\ , :c:func:`~A3DUnitGetFromValue`\ , :c:enum:`~A3DEUnits`
   
   
   **Parameters**
   
   
      **pModelFile**\ : A handle to a model file entity
   
      **pdUnit**\ : A location to an A3DDouble
   
   
   **Returns**
   
   
      ``A3D_SUCCESS`` on success, or an error code on failure
   
   




