.. highlightlang:: us .. index:: FileToField .. _filetofield: FileToField =========== .. us.tag FileToField ENGLISH Changed5100 Changed5501 :ref:`FileToField` reads a text file (ASCII file and UNICODE file with BOM) where the elements are arranged in rows and columns. The elements can be text, numbers and blank fields. .. function:: rmMat = FileToField(ssFileName) rmMat = FileToField(ssFileName, ssFieldSep) rmMat = FileToField(ssFileName, ssFieldSep, ssDecimalSep) rmMat = FileToField(ssFileName, ssFieldSep, ssDecimalSep, ssRecordSep) rmMat = FileToField(ssFileName, ssFieldSep, ssDecimalSep, ssRecordSep, hStatusWnd) rmMat = FileToField(ssFileName, ssFieldSep, ssDecimalSep, ssRecordSep, hStatusWnd, bQuotedNumberConversion) = FileToField(ssFileName) = FileToField(ssFileName, ssFieldSep) = FileToField(ssFileName, ssFieldSep, ssDecimalSep) = FileToField(ssFileName, ssFieldSep, ssDecimalSep, ssRecordSep) = FileToField(ssFileName, ssFieldSep, ssDecimalSep, ssRecordSep, hStatusWnd) = FileToField(ssFileName, ssFieldSep, ssDecimalSep, ssRecordSep, hStatusWnd, bQuotedNumberConversion) = FileToField(ssFileName) = FileToField(ssFileName, ssFieldSep) = FileToField(ssFileName, ssFieldSep, ssDecimalSep) = FileToField(ssFileName, ssFieldSep, ssDecimalSep, ssRecordSep) = FileToField(ssFileName, ssFieldSep, ssDecimalSep, ssRecordSep, hStatusWnd) = FileToField(ssFileName, ssFieldSep, ssDecimalSep, ssRecordSep, hStatusWnd, bQuotedNumberConversion) .. us.return **Return Value** *rmMat* is a real matrix. If an errors occurs, *rmMat* has only one element with the value 0.0, *smMat* is an empty string and *smType* contains the value "Error". *smMat* is a string matrix. *smType* is a string matrix in which the elements can have one of the following values: .. list-table:: :header-rows: 1 * - Value - Meaning * - ``""`` - (empty string) A number field. * - ``"B"`` - (Blank) A blank field. * - ``"S"`` - (String) A string field. .. us.params **Parameters** .. uparam:: ssFileName *ssFileName* is the file name. .. uparam:: ssFieldSep The first character of *ssFieldSep* is the field separator. Field separators: .. list-table:: :header-rows: 1 * - Value - Meaning * - ``" "`` - (default) multiple blanks or tab characters. * - ``"\b"`` - A single blank. * - ``"\t"`` - A single tab character. * - ``";"`` - A single semi-colon. * - ``","`` - A single comma. * - ``"x"`` - A single character. .. uparam:: ssDecimalSep *ssDecimalSep* is a period ``"."`` (default) or a comma ``","``. .. uparam:: ssRecordSep *ssRecordSep* is normally the newline character ``"\n"`` (default). .. 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:: bQuotedNumberConversion If *bQuotedNumberConversion* is TRUE (1) a number enclosed in quotes will be converted to a number field. If *bQuotedNumberConversion* is FALSE (0) the quoted string will always be treated as a string. Default value is TRUE (1). .. us.comment **Comment** The field size is limited to 4096 characters. The characters ``"\r\n"`` will replaced by the character ``\n``. The characters ``"\n"`` at the end of the file will be ignored. If this function is called with one return parameter, non-values will be replaced by the ``ERROR_VALUE``. Quotes ``"`` enclosing a field will be removed. Separators inside the quotes will be ignored. .. us.example **Example** File contents: :: 6.34 3.3 3.04 24 * rmData = FileToField("c:/test.dat") * rmData 6.34 3.30 3.04 24.00 File contents: :: N Mom 1000 12.3 2000 15.2 * = FileToField("c:/test.dat", " ", ".", "\n", 0) * rmD 0.00 0.00 1000.00 12.30 0.00 0.00 2000.00 15.20 * smS N Mom * smT SS BB * .. us.history **History** .. list-table:: :header-rows: 1 * - Version - Description * - R2013.1 - Maximum field size from 256 characters to 4096 characters expanded. .. seealso:: :ref:`ClipboardToField`, :ref:`StringToField`, :ref:`ExcelRead`, :ref:`fopen`, :ref:`nc_open` :sub:`id-1938973`