
######################
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. 
   
   
   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 A3DAsmProductOccurenceData.
   
   ``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``\ .
   
   
   
   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 :c:type:`~A3DDouble` 
   
   
   **Returns**
   
   
      ``A3D_SUCCESS`` on success, or an error code on failure
   
   




