If you need more flexibility than the built in logging methods offer, you can utilize the lower level file functions. These functions allow you to directly control the reading to and writing from files as well as many other features. Here's a list of the functions. All functions start with File. . Any errors while executing the functions will throw an error that starts with F.
File System Functions:
File.CopyFile(oldpath, newpath, don't overwrite existing): copies the oldpath file to newpath. If overwrite is 1 and newpath exists, that file will be overwritten. If overwrite is 0 and newpath exists, an error will occur.
File.Delete(filename): permanently deletes filename. Caution: You are not prompted to confirm!
File.GetDiskFreeSpace(drive path): returns the amount of disk space remaining on the given disk. drive path can be any valid path on the desired drive.
File.GetFileCreateTime(filename): return the time the file was created as determined by the operating system. The value is in DAQFactory time (i.e. seconds since 1970)
File.GetFileExists(filename): return 1 if filename exists, otherwise it returns 0
File.GetFileModifiedTime(filename): return the time the file was last modified as determined by the operating system. The value is in DAQFactory time (i.e. seconds since 1970)
File.MakeDirectory(directoryname): creates the given directory.
File.MoveFile(oldpath, newpath): moves the oldpath file to newpath. newpath cannot exist already or an error will occur.
File.RemoveDirectory(directoryname): removes the given directory if no files exist in it
File.Rename(oldname,newname): renames the oldname file to newname
Application: All the above functions allow you to manipulate your files and monitor the file system.
File List Functions:
File.GetFileNameList(path): returns an array of strings containing the names of all the files matching the given path and wildcard. The name does not include the path. For c:\mydir\myfile.txt, the name is myfile.txt.
File.GetFilePathList(path): same as above, but returns the whole path (c:\mydir\myfile.txt) for each file
File.GetFileTitleList(path): same as above, but only returns the file title (myfile) for each file.
Application: The above three functions are useful for retrieving a list of files. For example, if you wanted to open all the .csv files in a particular directory:
Private string strPaths = File.GetFilePathList("c:\data\*.csv")
if (IsEmpty(strPaths))
return // if nothing found, we have to return
endif
for (private count = 0, count < NumRows(strPaths), count++)
handle = File.Open(strPaths[count],1,0,0,1)
...
endfor
File / Folder Selection Functions:
File.FileOpenDialog([default file], [initial dir], [filter], [title]): all parameters are optional. This displays a standard windows dialog prompting the user for a file and returns the selected file path or an empty value if the user cancels out of the dialog (use IsEmpty() to check). This function can only be called by sequences running in the main application thread (triggered from a component)
File.FileSaveDialog([default file], [initial dir], [filter], [title]): same as above, but the user is prompted to save instead of open.
Application: These two functions are great for giving the user a way to specify a logging file. Apply them to a button labelled "Set Logging File". Here is a sample event that requests a file name and then sets the logging set Log to log to that name:
Private string strFileName = FileOpenDialog()
if (!IsEmpty(strFileName))
Logging.test.FileName = strFileName
endif
File.FolderSelectDialog([initial folder], [title]): pops up a window allowing the user to select a folder and returns a string with the selected folder path. This does not allow for file selection, just folder selection.
File Specific Functions:
All the rest of the functions are for working on a single file, either reading or writing, and require a file handle which is returned from the File.Open() function. This handle should be kept and passed to all functions that are going to work on the file opened. This allows you to have multiple files open at the same time. The handle returned provides a way to track which file you are working on. For example:
private FileHandle = File.Open("myfile.txt",1,0,0,0)
private string strIn = File.Read(FileHandle,10)
File.Close(FileHandle)
This script opens myfile.txt and reads 10 characters from it. It is good practice to always close your files when you are done with them, but if you forget, DAQFactory will close all open files when you quit the program.
File.Open(filename,read,write,append,text): all parameters are required. This opens the given filename for manipulation and returns a handle to the file. Set the read, write, and append parameters to 1 or 0 depending on if you want to open the file for reading, writing, and if writing, if you want to append to or overwrite an existing file. If the file does not exist, the append parameter is ignored. If you have write = 1 and append = 1 then the file pointer is automatically put at the end of the file. Otherwise it is placed at the beginning. The last parameter determines if the file is an ASCII text file or not. The Read() and Write() functions work differently for text files.
File.Close(handle): closes the given file. The handle is a number returned by the FileOpen() function.
File.CloseAll(): closes all files currently open. This is most useful if you lose track of a file handle (for example, stored in a private variable in a sequence that stopped before it closed the file).
File.Abort(handle): closes the given file ignoring any potential errors.
File.Read(handle,number of characters): If the file is opened with the text parameter set to 0, this function reads the given number of characters from the given file. Note that less characters may actually be read if the end of file is reached. If the file is opened with the text parameter set to 1, then the number of characters parameter is ignored and the function reads until it finds a newline character. The newline character is not returned. This function always returns a string. The file must be opened with the read parameter set to 1.
File.ReadDelim(handle, index, parse by, eol character, number of lines, [string]): This function allows the rapid reading of a delimited file such as the common files generated by DAQFactory logging sets. Parsing begins at the current file location, so if you have a header line, simply do File.Read(handle) to read the first line, putting the file location at the beginning of the second line. This function only works if the file is opened with the text parameter set to 1. This function will read the item specified by index, where 0 is the first item on each line, in a list parsed by parse by, and a line ended with eol character. This will be repeated for the specified number of lines, or if -1 is passed for number of lines, until the end of file is reached. If string is specified and is 1, the result will be an array of strings. Otherwise, each item will be converted into a number and an array of numbers is returned, with NaN's returned whenever an item cannot be converted properly to a number. You can specify a negative index to retrieve all items in one read, returning a 2d array. With larger files, it is actually slower to read the entire file at once than to read individual items one at a time.
Example: if you had the file:
1,2,3,4
5,6,7,8
ReadDelim(handle,2,",",chr(10),0) would return {3,7}
ReadDelim(handle,-1,",",chr(10),0) would return {{1,2,3,4},{5,6,7,8}}
File.ReadInter(handle, offset, interval, number of characters, number of intervals): This function allows the rapid reading of a binary file containing interleaved data. It will jump to the offset byte of the file, then read the specified number of characters. It will then jump by interval bytes (from the beginning of the block) and read the specified number of characters again, repeating for the specified number of intervals. If the number of intervals is set to 0, it will read until the end of file is reached. Typically this function will be used in combination with the To. and From. function to convert a binary data file into actual numbers. The file must be opened with the text parameter set to 0.
For example, let's say your file contains the bytes 0 1 2 3 4 5 6 7 8 9. If you did ReadInter(handle, 2, 4, 2, 2) you would get {{2,3},{6,7}}. You could then use, for example, the To.Word() function on the result to yield {770,1798}
File.Write(handle,string to write): writes the given string to the file. Note that you must add any desired CR/LF characters unless the file is opened with the text parameter set to 1 in which case a newline character is added automatically. For a file opened with the text parameter set to 0, the string is written verbatim with nothing added. The file must be opened with the write parameter set to 1.
File.WriteDelim(handle,{data}, delimiter, eol character): writes the given array of data to a delimited file with the specified delimiter and end of line character. This is basically the opposite of File.ReadDelim(). The file must be opened with the write parameter set to 1 and the text parameter set to 1.
Example:
File.WriteDelim(handle,{{1,2,3,4},{5,6,7,8}},",",chr(10)) would write this to the file:
1,2,3,4
5,6,7,8
File.Flush(handle): writes any cached data to disk. For performance reasons, Windows keeps some data in memory until a large enough block can be written to disk. This forces windows to write whatever it has kept in memory to disk.
File.Seek(handle,offset): jumps to the offset position from the beginning of the given file. Offset is in bytes and must be positive or zero.
File.SeekRelative(handle,offset): jumps the given offset from the current location in the file. Offset is in bytes and can be positive or negative or zero.
File.SeekToBegin(handle): jumps to the beginning of the file. This is the same as File.Seek(handle,0).
File.SeekToEnd(handle): jumps to the end of the file. This is the same as File.Seek(handle,File.GetLength(handle))
File.GetLength(handle): returns the number of bytes in the given file
File.SetLength(handle,new length): sets the given file to have a given length, truncating if necessary.
File.GetPosition(handle): returns the current position in the file that data will be read or written.
File.GetFileName(handle): returns the file name of the current file
File.GetFileTitle(handle): returns the file title of the current file
File.GetFilePath(handle): returns the full file path of the current file
