.. highlightlang:: us

.. index:: ExcelRead3

.. _excelread3:

ExcelRead3
==========

.. us.tag  ExcelRead3 ENGLISH New590 Changed5100

:ref:`ExcelRead3` reads MS-Excel files (.xls).

.. function::  smMatrix = ExcelRead3(ssFileName)
    smMatrix = ExcelRead3(ssFileName, ssSheetName)
    smMatrix = ExcelRead3(ssFileName, nSheet)
    <smMatrix, rmType> = ExcelRead3(ssFileName)
    <smMatrix, rmType> = ExcelRead3(ssFileName, ssSheetName)
    <smMatrix, rmType> = ExcelRead3(ssFileName, nSheet)
    <smMatrix, rmType> = ExcelRead3(ssFileName, ssSheetName, hStatusWnd)
    <smMatrix, rmType> = ExcelRead3(ssFileName, nSheet, hStatusWnd)
    <smMatrix, rmType> = ExcelRead3(ssFileName, ssSheetName, hStatusWnd, nOption)
    <smMatrix, rmType> = ExcelRead3(ssFileName, nSheet, hStatusWnd, nOption)
    <rmData, smString, rmType> = ExcelRead3(ssFileName)
    <rmData, smString, rmType> = ExcelRead3(ssFileName, ssSheetName)
    <rmData, smString, rmType> = ExcelRead3(ssFileName, nSheet)
    <rmData, smString, rmType> = ExcelRead3(ssFileName, nSheet, hStatusWnd)
    <rmData, smString, rmType> = ExcelRead3(ssFileName, ssSheetName, hStatusWnd)
    <rmData, smString, rmType> = ExcelRead3(ssFileName, nSheet, hStatusWnd, nOption)
    <rmData, smString, rmType> = ExcelRead3(ssFileName, ssSheetName, hStatusWnd, nOption)

.. us.return

**Return Value**

*smMatrix* contains the data of an Excel spreadsheet as a string matrix. If an
error occurs, *smMatrix* is a scalar string (``"Error"``) and *smType* contains
the value 999. *rmData* is a real matrix. A matrix element is valid if the the
corresponding type matrix (*smType*) element has the value 0 or a value smaller
than 100 depending on the parameter *nOption*.

*smString* is a string matrix. A matrix element is valid if the 
corresponding type matrix (*smType*) element has the value 2 or 100 depending 
on the parameter *nOption*.

*rmType* is a real matrix. The elements contain the data types of
the corresponding spread sheet cells.

If called without the the parameter *Option* the elements have the following 
value:

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

   * - Value
     - Description
   * - 0
     - Number
   * - 2
     - String
   * - 3
     - Empty cell

If *nOption* has the EXCEL_DETAILED_FORMAT set, the type elements contains
information about the cell format:

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

   * - Value
     - Description
   * - 0 to 10
     - Number, value is number of decimals.
   * - 19
     - Number, format undefined (General).
   * - 20
     - Number, time format e.g. 12:17:32.
   * - 21
     - Number, date format e.g. 02.30.2009
   * - 22
     - Number, date-time format. 02.30.2009 12:17:32
   * - 100
     - String
   * - 101
     - Empty cell
   * - 999
     - Error occurred

.. us.params

**Parameters**

.. uparam:: ssFileName

   *ssFileName* is the name of the Excel file,
   i.e. ``"c:\\excel\\test.xls"`` or :file:`c:/excel/test.xls`.

.. uparam:: ssSheetName

   *ssSheetName* is the sheet name of the Excel 5.0 file.
   If this parameter is not specified, the first sheet will be read.

.. uparam:: nSheet

   *nSheet* is the sheet index of the Excel 5.0 file.
   If this parameter is not specified, the first sheet will be read.
   Default value is 1.

.. 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.

.. uparam:: nOption

   *nOption* is an OR combination of the following values:

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

      * - Name
        - Value
        - Description
      * - EXCEL_IGNORE_USED_RANGE
        - 1
        - Matrix includes cell A1. Otherwise the used range is returned.
      * - EXCEL_DETAILED_FORMAT
        - 2
        - Type matrix contain cell format

   Default value is 0.

.. us.comment

**Comment**

All return matrices have the same number of rows and columns. A sheet can be
selected by its name or index *nSheet*.

A text cell can contain up to 2048 characters. Longer strings will be truncated.

For the following Excel sheet

.. list-table::
   :header-rows: 0

   * - ``-``
     - A
     - B
     - C
   * - 1
     - 
     - 
     - 
   * - 2
     - 
     - 123
     - 456

:ref:`ExcelRead` and :ref:`ExcelRead2` will return a 2 x 3 matrix. :ref:`ExcelRead3`
will return a 1 x 2 matrix, because the first row and the first column
is empty.

.. us.example

**Example**

::

   <rmData, smMat, rmType> = ExcelRead3("test1.xls", 1, 0, EXCEL_DETAILED_FORMAT);
   if (smMat[1] == "Error" && len(smMat) == 1) {
       MessageBox("test1.xls - Read error");
   }

.. us.history

**History**

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

   * - Version
     - Description
   * - 5.10.0
     - Returns Number format.

.. seealso::
   :ref:`overview-excel-files`,
   :ref:`ExcelRead`,
   :ref:`ExcelRead2`,
   :ref:`ExcelWrite`,
   :ref:`ExcelGetSheetNames`,
   :ref:`IsFileExcel`,
   :ref:`excel_open`,
   :ref:`FileToField`

:sub:`id-1011472`