FileWriteValue Function

Action

Writes structured data, for example a 4Test record, directly to a file on the host system.

Syntax

FileWriteValue(hFile, aValue)
Variable Description
hFile A handle to the file to write to. HFILE.
aValue The data to write to the file. ANYTYPE.

Notes

  • FileWriteValue writes each piece of data (aValue) on its own line in hFile. For example, if you call FileWriteValue three times on a new file, the resulting file will have three lines.

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

  • You can specify any 4Test data type as aValue. The data is written to the file as follows:
    • Strings are enclosed by double quotation marks.
    • Numbers are not enclosed by quotation marks.
    • Composite data, such as lists and records, are enclosed by curly braces, with elements separated by commas.
  • FileWriteValue raises an exception if the write operation fails.

  • You can use FileReadValue to read files created with FileWriteValue.

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

  • This function is not designed for remote access.

Example

[-] type PERSON is record
	[ ] STRING sName
	[ ] INTEGER iAge
	[ ] 
[-] STRING sFile = "people.dat"
	[ ] 
[-] testcase WriteToFile()
	[-] LIST OF PERSON lPerson = {...}
		[ ] {'Bob', 46}
		[ ] {'Emily', 16}
		[ ] {'Craig', 13}
	[ ] STRING sText = "Number of people:"
	[ ] INTEGER iCount = ListCount(lPerson)
	[ ] HFILE hFile
	[ ] PERSON Person
	[ ] 
	[ ] hFile = FileOpen (sFile, FM_WRITE) // Open the file
	[ ] 
	[ ] // write header information
	[ ] FileWriteValue(hFile, sText)
	[ ] FileWriteValue(hFile, iCount)
	[ ] 
	[ ] // write the data
	[-] for each Person in lPerson // Write to the file
		[ ] FileWriteValue (hFile, Person)
	[ ] FileClose (hFile) // Close the file
	[ ] 
	[ ] // Resulting contents of people.dat:
	[ ] // "Number of people:"
	[ ] // 3
	[ ] // {"Bob", 46}
	[ ] // {"Emily", 16}
	[ ] // {"Craig", 13}