3.7.5.16 File

File-obj

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:Layer propertie

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.

• Binary Data Properties

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

• ASCII Data Properties

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

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

1. Argument Format Errors

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

2. General Origin DLL Errors

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

3. File Object Specific Errors

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

4. Microsoft DOS File Access Errors

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.

• Binary File Methods

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

• ASCII File Methods

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

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.

// 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;

2. The following example is used to read data from a binary file, including some header information.

// 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;

3. This example will show how to import an ASCII file into a worksheet.

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