.. highlightlang:: us

.. index:: ExcelRead3

.. _excelread3:

ExcelRead3
==========

.. us.tag  ExcelRead3 GERMAN New590 Changed5100

:ref:`ExcelRead3` liest Excel-Dateien (.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

**Returnwert**

*smMatrix* enthält die Daten der Exceltabelle als String-Matrix. Falls ein Fehler
beim Lesen der Datei auftritt, hat *smMatrix* den skalaren Wert ``"Error"`` und 
*rmType* den Wert 999. *rmData* ist eine reelle Matrix. Ein Element der Matrix
ist gültig, falls das entsprechende Element der Typ-Matrix *rmType* den Wert 0
bzw. einen Wert kleiner 100 besitzt.

*smString* ist eine String-Matrix. Ein Element der Matrix ist gültig, falls 
der Wert des entsprechenden Elements der Typ-Matrix *rmType* 2 bzw. 100 ist.
Ungültige Elemente enthalten einen leeren String ``"Error"``.

*rmType* ist eine reelle Matrix, deren Elemente den Datentyp der entsprechenden
Zellen enthalten. Jedes Element der Matrix kann einen der folgenden Werte
annehmen:

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

   * - Wert
     - Bedeutung
   * - 0
     - Das Feld der Tabelle ist eine Zahl
   * - 2
     - Das Feld der Tabelle ist eine Zeichenkette (String)
   * - 3
     - Das Feld der Tabelle ist leer

Falls nOption den Wert EXCEL_DETAILED_FORMAT enhält, wird die Zahlenformatierung
im entsprechenden Typ-Element kodiert:

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

   * - Wert
     - Bedeutung
   * - 0 bis 10
     - Zahl, dargestellt mit entsprechend vielen Nachkommastellen.
   * - 19
     - Zahl mit nicht definiertem Format (General).
   * - 20
     - Zahl, die als Zeit formatiert ist, z. B. 12:17:32.
   * - 21
     - Zahl, die als Datum formatiert ist, z. B. 1.02.2009
   * - 22
     - Zahl, die als Datum-Zeit formatiert ist, z. B. 1.02.2009 12:17:32
   * - 100
     - Das Feld der Tabelle ist eine Zeichenkette (String)
   * - 101
     - Das Feld der Tabelle ist leer

.. us.params

**Parameter**

.. uparam:: ssFileName

   *ssFileName* ist der Name der zu lesenden Datei, z. B.:
   :file:`c:\\excel\\test.xls`.

.. uparam:: ssSheetName

   *ssSheetName* ist der Name der Tabelle (erst ab Excel 5.0 Dateien). Falls
   *ssSheetName* = "" ist, wird die erste Tabelle gelesen.

.. uparam:: nSheet

   *nSheet* ist der Index der Tabelle (erst ab Excel 5.0 Dateien).
   Der Index beginnt mit 1. 

.. uparam:: hStatusWnd

   Ist die Zugriffsnummer des Statusfensters, zur Ausgabe einer
   Fortschrittsanzeige (Defaultwert ist 0). Die Zugriffsnummer kann mit der
   Funktion :ref:`AppGetStatusBarHandle` erfragt werden.

.. uparam:: nOption

   *nOption* ist eine ODER-Verknüpfung der folgenden Werte:

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

      * - Name
        - Wert
        - Bedeutung
      * - EXCEL_IGNORE_USED_RANGE
        - 1
        - Matrizen beginnen be A1
      * - EXCEL_DETAILED_FORMAT
        - 2
        - Typ-Matrix mit Zahlenformatierung

.. us.comment

**Kommentar**

Alle Ausgabeparameter haben die gleiche Anzahl an Zeilen und Spalten. Auf eine
Tabelle einer Excel 5.0 Datei kann entweder über den Tabellen-Namen *ssSheetName*
oder über den Seiten-Index zugegriffen werden.

Wenn ein Fehler auftritt, haben die Ausgabeparameter nur ein Element mit dem Wert
999.0 bzw. ``"Error"``.

Der Text einer Zelle ist auf 2048 Zeichen begrenzt. Längere Text werden
nach 2048 Zeichen abgeschnitten. 

Die Funktion ersetzt :ref:`ExcelRead2`. Falls der Parameter
*nOption* den Wert EXCEL_IGNORE_USED_RANGE gesetzt ist, liefert die
Funktion immer eine Matrix mit der oberen linken Ecke A1. Ansonsten
liefert die Funktion den genutzten Bereich.

Für die Excel-Tabelle

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

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

liefern :ref:`ExcelRead` und :ref:`ExcelRead2` eine 2 x 3 Matrix. :ref:`ExcelRead3`
liefert nur eine 1 x 2-Matrix da die erste Zeile und die erste Spalte leer sind.

.. us.example

**Beispiel**

::

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

.. us.history

**History**

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

   * - Version
     - Description
   * - 5.10.0
     - Liefert Zahlenformat.

.. seealso::
   :ref:`uberblick-excel-dateien`,
   :ref:`ExcelRead`,
   :ref:`ExcelRead2`,
   :ref:`ExcelWrite`,
   :ref:`ExcelGetSheetNames`,
   :ref:`IsFileExcel`,
   :ref:`excel_open`,
   :ref:`FileToField`

:sub:`id-1011472`