
######################
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 :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``\ .
   
   
   
   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
   
   




