.. highlightlang:: us

.. index:: LotusRead

.. _lotusread:

LotusRead
=========

.. us.tag  LotusRead ENGLISH New320

The :ref:`LotusRead` function reads Lotus 1-2-3 :file:`.WK1` formatted files.

.. function::  smMatrix = LotusRead(ssFileName)
    <smMatrix, rmType> = LotusRead(ssFileName)
    <rmData, smString, rmType> = LotusRead(ssFileName)
    smMatrix = LotusRead(ssFileName, hStatusWnd)
    <smMatrix, rmType> = LotusRead(ssFileName, hStatusWnd)
    <rmData, smString, rmType> = LotusRead(ssFileName, hStatusWnd)

.. us.return

**Return Value**

*smMatrix* contains the data of a Lotus spreadsheet as a string matrix. If an
error occurs, *smMatrix* is a scalar string containing the text (``"error"``).
*rmData* is a real matrix. If the type matrix (*rmType*) element has the value
``0`` or ``2``, the corresponding element in *rmData* has the value 0.0.

*smString* is a string matrix. If the type matrix (*smType*) element has the
value ``"0"`` or smaller than ``"0"``, the corresponding element in *smString*
has the value ``""`` (empty string).

*rmType* is a real matrix. The elements contain the data types of the
corresponding spread sheet cells. If the value is smaller than ``0`` the values
specifies the number of decimal places (nDecimalPlaces = -val - 1):

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

   * - Value
     - Meaning
   * - < 0
     - Number field. The number of decimal places is -val-1. Example: -2 means 1 decimal place.
   * - 2
     - String field.
   * - 0
     - Blank (empty) field.

.. us.params

**Parameters**

.. uparam:: ssFileName

   *ssFileName* is the name of the Lotus :file:`WK1` file, e.g.
   ``"c:\\data\\test.wk1"`` or :file:`c:/data/test.wk1`.

.. uparam:: hStatusWnd

   Is the handle of the status bar window. It is used to display processing
   progress (default is 0).  The :ref:`AppGetStatusBarHandle` function returns
   this handle.

.. us.comment

**Comment**

All output parameters have the same number of rows and columns.

In case of an error, the output parameter has only one element with the value 0.0
or "error", i.e ``rmData[1;1] = 0.0``, ``smString[1;1] = "error"`` and
``smType[1;1] = "0"``.

.. us.example

**Example**

::

   def test_LotusRead()
   {
       loadlib("rs_lotus.dll")
       <rmData, smMat, rmType> = LotusRead("d:/uniplot/scriptsrc/test/test.wk1")
       if (smMat[1] == "error" && rmType[1] == 0) {
           error("test.wk1 - Lesefehler");
       }
       if (rmData[2;2] != 3) error();
   }
   test_LotusRead()

.. seealso::
   :ref:`IsFileLotus`

:sub:`id-773681`