File Handles and Remote File Input and Output Examples

This section contains the following examples:

A correctly set up test case.
Test cases with local handles and invalid handles.
Test case with double close.

Correctly set up test case

The file handle is a user defined variable whose scope is defined by the location of the variable declaration. You must be sure that the file is not closed before the variable goes out of scope. If the variable does goes out of scope, the file is lost until it is closed by the resource going out of scope.

On the remote files, you must also keep track as to which file handle belongs to which remote agent. The file handle itself has no information as to what remote host it belongs to. It is possible that a file handle for one remote host matches another host file handle. The file handle only know that it is local or remote and whether it is a generic file, INI file, or another file type.

The following test case is correctly set up for remote file handling:

	[-] TestCase FileCreate ()
		[ ] HANDLE hFile
		[ ] 
		[ ] hFile = FileOpen ("c:\myfile.txt", FM_WRITE, NULL)
		[ ] FileWriteLine (hFile, "This is a Test File line one.")
		[ ] FileWriteLine(hFile, "This is line two.")
		[ ] FileClose (hFile)
		[ ] // end of TestCase
	[ ] 
	[-] TestCase FileRead ()
		[ ] HANDLE hFile
		[ ] STRING sMyData
		[ ] BOOLEAN bDidRead
		[ ] 
		[ ] hFile = FileOpen ("c:\myfile.txt", FM_READ)
		[ ] bDidRead = FileReadLine (hFile, sMyData)
		[ ] 
		[ ] Print (sMyData)
		[ ] 
		[ ] FileClose (hFile)
		[ ] 
		[ ] // end of TestCase

Test cases with local handles and invalid handles

Here are two examples of test cases that have not been set up correctly. In the first test case, the file is not closed, and the handle is not saved because it is only local to the LocalFile test case. The second test case raises an exception due to the invalid handle.

	[-] TestCase LocalFile()
		[ ] HANDLE hLocalHandle
		[ ] 
		[ ] hLocalHandle = FileOpen ("c:myfile.txt",FM_WRITE)
		[ ] FileWriteLine (hLocalHandle, "test line")
		[ ] 
	[-] TestCase LostHandlfile()
		[ ] HANDLE hLocalHandle
		[ ] 
		[ ] FileWriteLine (hLocalHandle, "Test Line")
		[ ] FileClose (hLocalHandle)

The file operation is not restricted to other type of files, which means it uses FileOpen for INI file creation or modification and IniFileOpen to read the file. It is possible to create an INI file by using a generic file function such as FileWriteLine() or even to read the INI file through FileReadLine(). You can create a list file and later read it back by using the ListRead() function.

Note: Once the file is closed, its handles become invalid. If you close a file twice, the second attempt raises an exception. The same is true for the other file functions. With this in mind, be careful when you process a file with functions containing do..except and exception handling. A mistake can cause another exception to generate or a loss of file handles.

Test case with double close

In the following test case, the second FileClose causes an INVALID_FILE_HANDLE exception.

[-] TestCase DoubleClose ()
	[ ] Handle hFile
	[ ] 
	[ ] hFile = FileOpen ("c:\myfile.txt", FM_WRITE)
	[-] do
		[ ] SYS_FileWriteLine (hFile, "This will except because of local vs remote mismatch")
	[-] except
		[ ] Print ("Some error statement")
		[ ] FileClose (hFile)
	[ ] FileClose (hFile)

To fix the preceding test case, do one of the following:

Remove the FileClose (hFile) in the exception block.
Add either the ReRaise or the Raise function to continue the exception processing without returning to the main line.