3.7.5.16 File

The file object is used for reading and writing any file so that your data can be brought directly into an Origin worksheet. Please note that before Origin 7, the FUM (File Utility Module) is used for such functionality.

Properties:

The file object properties include three basic categories, file management properties, binary data properties, ASCII data properties, and error properties.

  • File Management Properties

File management properties refer to file management parameters.

Property Access Description
file.filename$ read/write, string Name of the last opened file. Note that the last opened file is not necessarily the name of the active file. If you provide a file name, then file.open() method without argument will open this file for read-only.
file.mode read/write, numeric This indicates what mode the file was opened in when using the file.open() method. The possible values are 0 for read-only (default), 1 for write-only, and 2 for read-write.
file.hFile read, numeric This is the handle of the active opened file.
file.name$ read/write, string The same as file.filename$.
file.openMode read/write, numeric The same as file.mode.
file.Version read, numeric OBSOLETE. Was the version of the DLL.
file.OrgVer read, numeric OBSOLETE. Was the minimum Origin version required.


  • Binary Data Properties

Binary data properties control binary data processing. They are typically set before reading or writing to a binary file.

Property Access Description
file.nByte read/write, numeric The same as file.nBytes.
file.nBytes read/write, numeric This property designates how many bytes there are per data value. Depending upon the command and type of data, the values could be 1 (default), 2, 3, 4, 8, or 10. Note that 3 has limited support and 10 is no longer supported.
file.byteOrder read/write, numeric This property indicates what order two and four byte data is read in (or written out) if read from a file (or written to a file). Values could be 0 (low byte first, default), or 2 (high byte first).
file.signed read/write, numeric This property indicates if read data should be interpreted as signed or unsigned. Values could be 0 (unsigned, default), or 1 (signed).
file.skip read/write, numeric This property designates how many bytes in the file should be skipped after each data point is read (or written) when using the methods file.Aread(), file.ReadBinRow(), or file.Awrite().
  • ASCII Data Properties

ASCII data properties control ASCII data processing. They are typically set before reading or writing to an ASCII file.

Property Access Description
file.nLineMode read/write, numeric This designates the ASCII line ending mode used. Values could be 0 (Carriage Return and Line Feed - Windows & DOS, default), 1 (Line Feed - Unix, Linux, Mac OS X) or 2 (Carriage Return - Apple up to OS-9).
file.nLinesMode The same as file.nLineMode.
file.listSep read/write, numeric This indicates the numeric value of the current token separator (sometimes called list separator, or delimiter) to be used for ASCII import/export. The default is "," which corresponds to file.listSep = 44. The list separator may also be set using the ASCII method file.listSep(character) - e.g. file.listSep(Z). This method allows the delimiter to be set without knowing the numeric value of the character.


  • Error Properties

There are four error categories when using the file object, including argument format errors, general Origin DLL errors, file object specific errors, and Microsoft DOS file access errors. The first three types are reported in the property file.error, and the last is reported in file.sysErr.

Property Access Description
file.error read, numeric This is used to report argument format errors, general Origin DLL errors, and file object specific errors. See the details in the tables below.
file.sysErr read, numeric System error number.
  1. Argument Format Errors
  2. Any method that receives arguments will check that the arguments are of the correct format. If there is an error in any argument format, format bit 7 (ARG_FORMAT) of file.error will be set. In addition, each argument field that is found to be in error will have its associated bit set. For example, if the first argument were bad or missing, the error code would be 128 (ARG_FORMAT) plus 1 (1ST_ARGUMENT), or 129.

    Constant Error Number Bit
    1ST_ARGUMENT 1 bit 0
    2ND_ARGUMENT 2 bit 1
    3RD_ARGUMENT 4 bit 2
    4TH_ARGUMENT 8 bit 3
    ARGUMENT_PASSED_4TH 16 bit 4
    ILLEGAL_ARGUMENT_VALUE 64 bit 6; format bit 7 NOT set
    ARG_FORMAT 128 bit 7
  3. General Origin DLL Errors
  4. Constant Meaning Value
    DATASET_NOT_FOUND No dataset found 1
    WORKSHEET_NOT_FOUND No worksheet found 2
    ARGUMENT_OUT_OF_RANGE Argument list is out of range 3
    MICS_LOW_LEVEL_ROUTINE_FAILED Low level routine failed 4
    OUT_OF_MEMORY Not enough memory 5
    ERROR_ON_ORIGIN_CALL Error on Origin call 6
  5. File Object Specific Errors
  6. Constant Meaning Value
    HFILE File handler error 1024
    FILE_CREATION File creation error 1025
    OPEN_FILE File open error 1026
    WRITE_FILE File writing error 1027
    GENERAL_FILE General file operation error 1028
    READ_FILE File reading error 1029
  7. Microsoft DOS File Access Errors
  8. File.sysErr gives you access to Microsoft DOS file access errors. Refer to the following reference list for an explanation of each system error.

    Constant Meaning Value
    ENOENT No such file or folder 2
    E2BIG Argument list is too long 7
    ENOEXEC Exec error format 8
    EBADF Bad file number 9
    ENOMEM Not enough memory 12
    EACCES Permission denied 13
    EEXIST File exists 17
    EXDEV Cross-device link 18
    EINVAL Invalid argument 22
    EMFILE Too many open files 24
    ENOSPC No space left on device 28
    EDOM Math error 33
    ERANGE Result is too large 34
    EDEADLOCK Resource deadlock would occur 36

Methods:

There are three basic categories of methods in file object, general file management methods, binary file methods, and ASCII file methods.

  • General File Management Methods

General file management methods include all non-data actions. For example, opening and closing files, and getting or setting the file pointer, are general file management methods.

Method Description
file.close([hFile]) Close the opened file. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • 0: successful
  • -1: failed
  • --: an invalid hFile is specified
file.closeAll() Same as file.closeAllFiles().
file.closeAllFiles() Close all opened files.

Return value:

  • 0: successful
  • -1: failed
file.delete(filename$) Delete the specified file from disk.

Return value:

  • 1: successful
  • 0: error occurred
  • --: the specified file does not exist
file.exist(filename$) Same as file.exists().
file.exists(filename$) See if the specified file exists, the same as file.exist().

Return value:

  • 1: file exists
  • 0: not exist
file.fastForward([hFile]) Same as file.toEnd().
file.fForward([hFile]) Same as file.toEnd().
file.getPos([hFile]) Get the current position of the file pointer relative to the beginning of the file in bytes. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the position of the file pointer if successful
  • -1 and set file.error property if failed
file.listAll() Same as file.listAllFiles().
file.listAllFiles() List all opened files.

Return value:

  • 1: if there are files opened, and list them
  • 0: if there are no files opened
file.open(filename$[, mode]) Open the specified file. The mode may be set to 0 (read-only), 1 (write-only), or 2 (read and write). When no mode is specified the default is the value of the property file.mode. The file.mode defaults to read only if not set by the user. If the designated file does not exist, it is created, opened, and will allow you to read or write to it.

Return value:

  • the file handle if successful
  • -1 if failed
file.remove(filename$) Same as file.delete().
file.reset() Reset all the file object properties to their default values.

Return value:

  • 0: successful
  • -1: failed
file.rewind([hFile]) Reset the file pointer to the beginning of the file. Defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • 0: successfully reset
  • -1 and set file.error property: error occurred
file.setPos(pos[,hFile]) Set the file pointer to the position specified by the user, counting in bytes starting at 0. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the new position of the file pointer if successful
  • -1 and set file.error if failed
file.size([hFile]) Get the size of a file. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the size of the file in bytes
  • -1 and set file.sysErr if failed
file.switchMode(nMode) Change the mode of the active opened file. nMode can be 0 for read-only (default), 1 for write-only, and 2 for read-write.
file.toBegin([hFile]) Same as file.rewind().
file.toBeginning([hFile]) Same as file.rewind().
file.toEnd([hFile]) Set the file pointer to the end of the file. hFile defaults to the file handle of the most recently used file if not specified by the user. This is useful if you want to append data to the end of a file of unknown length.

Return value:

  • the number of bytes in the file
  • -1 and set file.error if failed
file.toStart([hFile]) Same as file.rewind().
file.wksBlock(wksName$, colBegin, colEnd, rowBegin, rowEnd) Read numeric data from the currently opened file into the worksheet, wksname, beginning at colBegin and ending at colEnd. If non-numeric data is encountered, the entire line is placed in %Z and this operation terminates.

Specify rowBegin and rowEnd arguments, or specify 0 for rowEnd to read the block until EOF (end of file).

Please note that, colBegin, colEnd, rowBegin and rowEnd mean the column and row in the file, but not the column and row in the worksheet.

  • Binary File Methods

Binary file methods include the reading and writing of binary data between files and worksheets or LabTalk variables.

Method Description
file.ARead(dataset$, start, end, binType[, hFile]) Read an array of data from a file and write to a worksheet. dataset$ is the name of the specified column of the worksheet, WksName_ColName. start and end are the starting and ending rows within the column. Column numbering starts at one. binType designates what type of data is being read: 0 (integer), 1 (float), 2 (BCD). When binType is 0 (int), the property file.signed determines if the values are signed, and the property file.byteOrder determines the byte order. The data will be stored as double point values in the worksheet. The number of bytes per data point is taken from the property file.nBytes. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the number of data points read, (end - start) + 1
  • a null value (--) if failed
file.arrayRead(dataset$, start, end, binType[, hFile]) Same as file.ARead().
file.arrayWrite(dataset$, start, end, binType[, hFile]) Same as file.AWrite().
file.AWrite(dataset$, start, end, binType[, hFile]) Read an array of data from a worksheet and write to a file. dataset$ is the name of the specified column of the worksheet, WksName_ColName. start and end are the starting and ending rows within the column. binType designates what type of data is being written: 0 (integer), 1 (float), 2 (BCD). Please note that BCD is not supported for file.AWrite(). When binType is 0 (int), the property file.signed determines if the values are signed, and the property file.byteOrder determines the byte order. hFile defaults to the file handle of the most recently used file if not specified by the user. The number of bytes per data point is taken from the property file.nBytes. 3 byte data is not supported.

Return value:

  • the number of data points written, (end - start) + 1
  • a null value (--) if failed
file.doubleRead([hFile]) Same as file.DRead().
file.DRead([hFile]) Read a double point value from a file. The value will consist of 8 bytes. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the double point value read
  • file.error and file.sysErr will be set if there is an error
file.doubleWrite(value[, hFile]) Same as file.DWrite().
file.DWrite(value[, hFile]) Write a double point value to a file. value can be a number or a variable name. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the number of bytes of the value, 8
  • a null value (--) and set file.error and file.sysErr if failed
file.floatRead([hFile]) Same as file.FRead().
file.FRead([hFile]) Read a float value from a file. The value will consist of 4 bytes. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the float value read
  • file.error and file.sysErr will be set if there is an error
file.floattrite(value[, hFile]) Same as file.FWrite().
file.FWrite(value[, hFile]) Write a float value to a file. The value can be a number or a variable name. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the number of bytes of the value, 4
  • a null value (--) and set file.sysErr if failed
file.integerRead([nBytes[, hFile]]) Same as file.Read().
file.integerWrite(value[, nBytes[, hFile]]) Same as file.Write().
file.intRead([nBytes[, hFile]]) Same as file.Read().
file.intWrite(value[, nBytes[, hFile]]) Same as file.Write().
file.lDoubleRead([hFile]) Alias for file.LDRead() (Obsolete).
file.lDoubleWrite(value[, hFile]) Same as file.LDWrite() (Obsolete).
file.LDRead([hFile]) Read a long double (10 byte) value from a file. This method is obsolete since Microsoft compilers now map long double to double.
file.LDWrite(value[, hFile]) Write a value to a file as a long double (10 bytes). This method is obsolete since Microsoft compilers now map long double to double.
file.longDoubleRead([hFile]) Same as file.LDRead() (Obsolete).
file.longDoubleWrite(value[, hFile]) Alias for file.LDWrite() (Obsolete).
file.Read([nBytes[, hFile]]) This reads an integer of nBytes from the file hFile. nBytes defaults to the number of bytes specified by the property file.nBytes if not set here. This will default to 1 if never set by the user. The byte order is controlled by the property file.byteOrder. This defaults to low byte first. Signed or unsigned is controlled by the property file.signed. The default is unsigned. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the integer read
  • 0 if no value
file.ReadRowBin(wksname$, nToken, binType[, hFile]) Read an array of binary data from a file and write to a worksheet. wksname$ is the name of the worksheet, e.g., Book1 (case-insensitive). nToken is the number of data points to be read. binType designates what type of data is being read: 0 (integer), 1 (float), or 2 (BCD). The number of bytes per data point is taken from the property file.nBytes. When binType is 0 (int), the property file.signed determines if the values are signed, and the property file.byteOrder determines the byte order. The data will be written to the worksheet as a row. The row will be appended to the last row with data in the worksheet. The first column will be the left-most column of the worksheet. The data will be stored to the worksheet as double floats. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the number of data points read
  • a null value (--) if failed
file.Write(value[, nBytes[, hFile]]) Write an integer, value, to a file. The value can be either a number or a variable. nBytes defaults to 1. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the number of bytes of the value, nBytes
  • a null value (--) if failed
  • ASCII File Methods

ASCII file methods include the reading and writing of ASCII data between files and worksheets or LabTalk variables.

Method Description
file.Cread(strVarLetter, nchar[, hFile]) Read nchar characters from a file, and store in strVarLetter. strVarLetter is a specified letter (A-Z), e.g., M, then print the string by %M = . hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the length of the string read
  • a null value (--) if failed
file.LineRow(wksname$[, hFile]) Read an array of ASCII data from a file and write to a worksheet. wksname$ is the name of the worksheet, e.g., Book1 (case-insensitive). Tokens in the file are separated by the character defined by file.listSep(). End of line strings (CR) in the file will terminate the read, as will the end of the file. The data to be read must be in ASCII format. The data will be written to the worksheet as a row. The row will be appended to the last row with data in the worksheet. The first column will be the left-most column of the worksheet. The data will be stored in the worksheet as double floats. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the number of tokens read if successful
  • a null value (--) if failed
file.ListSep(character) This method is one of two ways to set the list separator to be used in importing or exporting an ASCII file.

This method actually sets the property file.listSep. Therefore, another way to set the separator is to manually set the file.listSep property to the numeric value of the ASCII code corresponding to the desired delimiter. However, the method is more user-friendly since it allows one to set the delimiter without knowing the numeric value of the character.

Example: file.listsep(z); // Sets list separator to 90, the ASCII value of lower case z.

Return value is undefined.

file.LRead(strVarLetter[,hFile]) Read a line (including line ending character) from a file, and use strVarLetter to store the string. strVarLetter is a specified letter (A-Z), e.g., M, then print the string by %M = . hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the length of the line read
  • 0 if a blank line or end-of-file is reached
  • -1 if failed
file.LWrite("string"[, hFile]) Write a line (string + line ending mode) to a file. hFile defaults to the file handle of the most recently used file if not specified by the user. This function uses the file.nLineMode property as the line ending mode.

Return value:

  • the length of the line written, including line ending mode
  • 65534 or a null value (--) if failed
file.ReadArray(dataset$, start, end[, hFile]) Read an array of ASCII data from the file, convert to double float, and write to a worksheet. dataset$ is the name of the specified column of the worksheet, e.g., data1_a (case-insensitive). start and end are the starting and ending positions within the column. The data to be read must be in ASCII format. The property file.listSep is used as the delimiter between ASCII data points. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the number of data points read, (end - start) + 1
  • a null value (--) if failed
file.ReadRow(wksname$, nToken[, hFile]) Read an array of ASCII data from a file and write to the a worksheet as a row. wksname$ is the name of the worksheet, e.g., Book1 (case-insensitive). nToken is the number of tokens to be read. Tokens in the file are separated by the character defined by file.listSep(). The data to be read must be in ASCII format and separated by the delimiter specified by the property file.listSep. The data will be written to the worksheet as a row. The row will be appended to the last row with data in the worksheet. The first column will be the left most column of the worksheet. The data will be stored to the worksheet as double floats. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the number of tokens read
  • a null value (--) if failed
file.readToken(strVarLetter, nToken[, hFile]) Read nToken tokens (including list separators) from a file, and store in strVarLetter. strVarLetter is a specified letter (A-Z), e.g., M, then print the string by %M = . The tokens must be in ASCII and separated by the list separator defined by the property file.listSep. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the length of the string read
  • a null value (--) if failed
file.Tread(strVarLetter, nLine[, hFile]) Read nLine lines (including line ending mode) from a file, and store in strVarLetter. strVarLetter is a specified letter (A-Z), e.g., M, then print the string by %M = . hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the length of the string read
  • a null value (--) if failed
file.Twrite("string[, hFile]) Write a string to a file in the first line. If the first line contains string, the corresponding positions will be replace by the written string. hFile defaults to the file handle of the most recently used file if not specified by the user.

Return value:

  • the length of the string, including the end of line characters
  • 65534 or a null value (--) if failed

Examples:

  1. This example is used to browse an ASCII file and open it, then set the delimiter to comma, and then read the data into a worksheet with 8 rows and 12 columns.
  2. // start with standard worksheet
    for (ii=wks.ncols;ii>0;ii-=1) {
    	del %(%H,ii);	
    };
    wo -a 2;
    wks.col1.type=4;
    doc -uw;
    
    // get ASCII file name in %A, path in %B
    getfile *.dat;
    // open the file, read-only
    hfile = file.open(%B%A);
    // set delimiter to comma
    file.listsep(",");
    // take 96 values of data and import into
    // 8 rows of 12 columns each
    // read the data
    loop (row,1,8) {
        tokensread = file.readrow(%H,12);
        type -q "Importing Row $(row)";
        if (tokensread<=0) break;
    }
    file.close();
    doc -uw;
  3. The following example is used to read data from a binary file, including some header information.
  4. // start with standard worksheet
    for (ii=wks.ncols;ii>0;ii-=1) {
    	del %(%H,ii);	
    };
    wo -a 2;
    wks.col1.type=4;
    doc -uw;
    
    // get binary file name into %A, path into %B
    getfile *.bin;
    hfile = file.open(%B%A);
    
    // the first 8 header fields are 4 bytes each
    magic = file.read(4);
    checksum = file.read(4);
    start = file.read(4);
    stop = file.read(4);
    incr = file.read(4);
    dwell = file.read(4);
    drive = file.read(4);
    numpts = file.read(4);
    // the next 4 header fields are 2 bytes each
    comments = file.read(2);
    evaluation = file.read(2);
    version = file.read(2);
    confidence = file.read(2);
    // read a string
    file.cread(A,10);
    // set data size and sign
    file.nbytes=2;
    file.signed=1;
    // read arrays of data of size 'numpts'
    file.aread(%H_A,1,numpts,0);
    file.aread(%H_B,1,numpts,0);
    // display header information in the Script Window
    type -a;
    magic = ;
    checksum = ;
    start = ;
    stop = ;
    incr = ;
    dwell = ;
    drive = ;
    numpts = ;
    comments = ;
    evaluation = ;
    version = ;
    confidence = ;
    
    file.close();
    doc -uw;
  5. This example will show how to import an ASCII file into a worksheet.
  6. newbook;  // create a new workbook
    file.filename$ = system.path.program$ + "Samples\Curve Fitting\Gamma.dat";
    file.open();  // open the file, read-only
    file.listSep("\t");  // set delimiter to "\t"
    int nCurPos = file.getPos();  // get current position of file
    int nSize = file.size();  // get file size
    for(; nCurPos < nSize; )  // loop to read all data
    {
    	file.readRow(%H, 2);  // read one row, with 2 data
    	nCurPos = file.getPos();
    }
    file.close();  // close the file