.. highlightlang:: us

.. index:: updf_dump

.. _updf_dump:

updf_dump
=========

.. us.tag  updf_dump NOTREADYENGLISH updf updf-misc New560 Changed5401

:ref:`updf_dump` saves a complete updf file in a directory. For storages a new
subdirectory will be created. Properties will be saved in xml files. Streams will
be saved in binary files.

.. function::  bool = updf_dump(stg, ssDir)
               bool = updf_dump(stg, ssDir, mode)

.. us.return

**Return Value**

*bool* is TRUE (1), if the function was successful and otherwise FALSE (0).

.. us.params

**Parameters**

.. uparam:: stg

   *stg* is a storage object (see :ref:`updf_create_file`, :ref:`updf_open_file`,
   :ref:`updf_create_storage`).

.. uparam:: ssDir

   *ssDir* is the name of a directory.

.. uparam:: mode

   Is one of the following values:

   .. list-table::
      :header-rows: 1

      * - Value
        - Description
      * - 0 or UPDF_FAIL_IF_EXIST
        - This is the default value, if *mode* is not specified. If a file or a directory with the name *ssDir* already exists, the function will fail.
      * - UPDF_REMOVE_DIRECTORY
        - The directory or file will be deleted.
      * - UPDF_OVERWRITE
        - Directory or file will be overwritten.
      * - UPDF_PROPSONLY
        - Saves only the properties of the storage *stg*.

.. us.comment

**Comment**

   The output of the properties are xml files with the extension :file:`._props_`. 
   Example: If a stream "Test Stream" exists the file name would be
   "Test Stream._props_".

   .. code-block:: xml

      <?xml version="1.0" encoding="utf-8" ?> 
      <props version="1.0">
        <p n="Units" t="s">
          <v>1/s</v> 
        </p>
        <p n="add_offset" t="f">
          <v>17.2</v> 
        </p>
      </props>

   The _props_ files contains three XML elements <props/>, <p/> and <v/>. <p/>
   has four attributes: n (Name), t (Typ), nr (Number of rows), nc (Number of
   columns). The following data types are available:

   .. list-table::
      :header-rows: 1

      * - Value
        - Descripion
      * - d
        - double
      * - f
        - float
      * - i8
        - int8. Signed 8 bit integer.
      * - ui8
        - uint8
      * - i16
        - int16
      * - ui16
        - uint16
      * - i32
        - int32
      * - ui32
        - uint32
      * - i64
        - int64
      * - ui64
        - uint64
      * - s
        - utf-8-String.
      * - b
        - blob (binary large object) base64 coded.

   The table identifier can have a suffix "v" for vector or "m" for matrix. 
   Example: "ui64" (unsigned int 64 bits) "ui64v" (vector of "ui64") "ui64m"
   (matrix of "ui64"). For a vector the attribute nr must be specified. For a
   matrix *nr* and *nc* must be specified.

.. us.example

**Example**

.. include:: ../include/test_updf_dump.ic

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2012.1 (5.40.1)
     - New flag ``UPDF_PROPSONLY``.
   * - 5.6.0
     - New.

.. seealso::
   :ref:`overview-updf-files`,
   :ref:`updf_gen`

:sub:`id-2043439`