SilkTest File Operations

FileOpen function

Action

Opens a file on the host system.

Syntax

hFile = FileOpen (sPath, fmMode [, fsShare[, ftType]])

Variable          Description

hFile    A handle to the opened file. HFILE.

sPath   The name of the file to open. STRING.

fmMode          The mode to open the file with. FILEMODE.

fsShare            Optional. Specifies file-sharing behavior.  FILESHARE.

ftType  Optional. Specifies the format of the text file to be created. Available only with SilkTest International.  Only has an affect when creating a new file. FILETYPE

Notes

FileOpen opens the file identified by sPath, or creates it, depending on the mode you specify (see below). This function returns a file handle of type HFILE, which you pass to other file functions.

Any open local files are automatically closed and saved at the end of a test script.

The File functions that control writing to a file (such as FileWriteLine, FileWrite Value, and their SYS_ equivaltents) do not test your accessibility to a file. This means that you cannot write information to a file that has been opened in read only mode with FileOpen(). The function will successfully return, but no information is actually written to the file. There is no error message that indicates this.

Example

Here’s a simple example which checks a BOOLEAN value presumably passed into the function/testcase) to determine whether or not the file should be shared and then sets the file-sharing behavior accordingly.

// output file handle

            HFILE OutputFileHandle

            FILESHARE fShare

           

            // check to see if file opening should lock out other writers

                        if (bExclusiveWrite == TRUE)

                            fShare = FS_DENY_WRITE

                        else

                            fShare = FS_DENY_NONE

                       

                        // now open the file

            OutputFileHandle = FileOpen ("mydata.txt", FM_WRITE, fShare)

FileReadLine function

Action

Returns the next line of a file on the host system.

Syntax

bDidRead = FileReadLine (hFile, sLine)

Variable          Description

bDidRead        Whether a line was read. BOOLEAN.

hFile    The handle of the file to read a line from. HFILE.

sLine    A variable to hold the line. out STRING.

Notes

FileReadLine reads the next line of a file and returns the contents of the line in sLine. Typically, you open a file with FileOpen, and then read it line by line with FileReadLine until FALSE is returned.

You can get a handle to a file (an HFILE) by calling the FileOpen function with the FM_READ filemode data type. An exception is raised if an invalid file handle is specified.

FileReadLine returns TRUE if a line was read, or FALSE if the end of the file was encountered.

FileReadLine modifies the sLine variable. Any previous value in sLine is discarded.

FileReadLine considers the end-of-line character to be a carriage return (CR), even if it is not combined with a linefeed (LF) character. In other words, both CR and CR-LF are considered line terminators.

4Test recognizes that it has reached the end of a file (EOF) by no longer reading that file – in other words, by receiving a null string. It does not read any special character at the EOF.

For SilkTest, EOF is indicated by a FALSE bDidRead return and a null string is indicated by a TRUE bDidRead return and a null string.

The SilkTest file read functions can handle line lengths up to 4K characters. This applies to the FileReadLine function, FileReadValue function, SYS_FileReadLine function, and SYS_FileReadValue function.

Examples

HFILE hFile

            STRING sLine

            testcase FileReadExample ()

               hFile = FileOpen ("mydata.txt", FM_READ)

                           while (FileReadLine (hFile, sLine))

                              // statements to process this line

                           FileClose (hFile)

You can also read from a file opened in file mode FM_UPDATE, in order to begin overwriting the file in the middle instead of at the beginning. For example:

[ ] STRING s

            [ ] INTEGER i

            [ ] HFILE hFile = FileOpen ("{GetProgramDir ()}\Sample.txt", FM_UPDATE)

            [-] for i = 1 to 2

                    [ ] FileReadLine (hFile, s)

            [ ] FileWriteLine (hFile, "*New one*")

            [ ] FileWriteLine (hFile, "*This is new line two*")

            [ ] FileClose (hFile)

FileClose function

Action

Closes a file on the host system.

Syntax

FileClose (hFile)

Variable          Description

hFile    The handle of the file to close. HFILE.

Notes

FileClose closes the file identified by hFile. You return a handle to the file (an HFILE) by calling the FileOpen function.

SilkTest raises the exception E_HANDLE if the file has already been closed or if an invalid file handle is specified.

Example

// output file handle

                        HFILE OutputFileHandle

                        // Create and open file for writing,

                        // write to it, then close

                        OutputFileHandle = FileOpen ("mydata.txt", FM_WRITE)

                        FileWriteLine (OutputFileHandle, "First line of text")

                        FileClose (OutputFileHandle)

FileWriteLine function

Action

Writes a line of text to a file on the host system.

Syntax

FileWriteLine (hFile, sLine)

Variable          Description

hFile    The handle of the file to write to. HFILE.

sLine    The text to write. STRING.

Notes

FileWriteLine writes the specified string to the file identified by hFile. It automatically appends the appropriate character or characters (for example, a carriage return/line feed sequence) needed to delimit a line of text on the current platform.

You can get a handle to a file (an HFILE) by calling the FileOpen function with the filemode data type set to either FM_WRITE, FM_UPDATE, or FM_APPEND.

The File functions that control writing to a file do not test your accessibility to a file. This means that you cannot write information to a file that has been opened in read only mode with FileOpen(). The function will successfully return, but no information is actually written to the file. There is no error message that indicates this.

Example

HFILE FileHandle

                       

            // Open file, append line, and close

            FileHandle = FileOpen ("mydata.txt", FM_APPEND)

            FileWriteLine (FileHandle, "next line of text")

            FileClose (FileHandle)

Example:

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

               BOOL bDidRead

  

               hFile = FileOpen ("c:\myfile.txt", FM_READ)

               bDidRead = FileReadLine (hFile, sMyData)

              

               Print (sMyData)

FileClose (hFile)