FileReadMessage

The function FileReadMessage reads a message (that is, a string of characters) from a text file, and then it writes that message to a project tag.

Syntax

FileReadMessage(strFilename,numOffset,strMessageTag,numCharsToRead)

FileReadMessage ( strFilename , numOffset , strMessageTag , { numCharsToRead | 0 } )

strFilename

The file path and/or name of the text file. If the file is located inside your project folder, you can specify either just the file name or the file path relative to that folder. If the file is located outside your project folder, you must specify the absolute file path.

Note: Follow the conventions of the target platform for the file path and name, and separators. For example, a file path in Windows starts with a drive letter and uses backward slashes as separators (C:\path\to\file), while a file path in Linux starts at the root directory and uses forward slashes as separators (/path/to/file).

numOffset

The number of bytes to skip in the text file before reading characters. To read from the start of the file, numOffset should be 0.

You can use this parameter to start reading from any position in the file, as long as you know how many bytes to skip. In most cases, you will simply take the value returned by the previous execution of this function (see "Returned value" below) and use it to resume reading where you previously stopped.

However, if you already know the structure of the file and where you want to start in it, you can do that. For example, if you know that each line of the file is exactly 100 bytes and you want to read from the start of the fifth line, numOffset should be 400.

Note: The number of bytes per character in a file depends on the text encoding (that is, ANSI, UTF-8, UTF-16, or other), the byte order, and the language or character set.

strMessageTag

The name of the project tag (String type) that will receive the message read from the text file.

Note: If the tag name is not enclosed in quotes, the function will try to use the value of specified tag.

numCharsToRead

The number of characters to read from the text file, starting from the position specified by numOffset. If this value is 0, all characters up to the next line feed (LF) will be read.

Returned value

If this function is successfully executed, it returns the position of the last byte read from the text file (including 0 if no bytes were read), which be used in turn as the offset for the next message to be read.

If this function fails, it returns a negative value.

Notes

This function can be used to read from any plain text file, as long as the correct file extension is specified in strFilename.

Examples

FileReadMessage("C:\Data\Messages01.txt",0,"MsgTag",0)

FileReadMessage("Messages02.txt",0,"MsgTag",140)