Sets the read/write position (in characters, not bytes) in an open file on a target machine.
iPos = SYS_FileSetPointer (hFile, iNewValue [, SetMode] )
| Variable | Description |
|---|---|
| iPos | New read/write position in characters in the file. INTEGER. |
| hFile | The handle of the file to set the read/write position in. (You get a file handle by calling the SYS_FileOpen function.) HFILE. |
| iNewValue | Value that specifies new position, subject to value of SetMode. INTEGER. |
| SetMode | Optional. Mode to use to set new position. FILEPOS. |
SYS_ FileSetPointer is executed by the Agent process, not the Silk Test Classic process; but it is essentially the same as FileSetPointer. To affect the host process, use the function with the hHost notation or machine handle operator. For more information about the machine handle operator and hHost, see Machine handle operator.
SYS_FileSetPointer sets the read/write position in an open file. It uses the value specified for iNewValue in different ways, depending on what was specified for SetMode, which is of type FILEPOS. The value of iNewValue must be such that the new position is between 0 and the end of the file (EOF). iNewValue can take any of the following values.
| Value | How the Read/Write Position is Set |
|---|---|
| FP_START | (Default) The read/write position is set to iNewValue, which must be positive. |
| FP_END | The read/write position is set to the file length iNewValue characters before the end of the file. iNewValue must be a negative number. For example, iCurrentPos = SYS_FileSetPointer (openFile, -4, FP_END) sets the position to 4 characters before the end of the file. If you enter a positive number for FP_END, you will receive an error message. |
| FP_RELATIVE | The read/write position is set to the current position + iNewValue. |
SYS_FileSetPointer returns the new read/write position. The new position cannot go past the end of file or be set before the beginning of the file. If the new position is beyond the borders of the file, Silk Test Classic raises an exception condition. The set position range is from the first character of the file to the last character of the file. No other position is valid.
The file header is not part of the file range. This means that the file’s first character can be up to 3 bytes into the raw file – and that is counted as the first position in the file.
This function is not designed for local access.
You can use SYS_FileSetPointer with the Open Agent or the Classic Agent. When setting the pointer after the end of the file, the Open Agent does not throw an exception, while the Classic Agent does throw an exception.
INTEGER iCurrentPos
HFILE openFile
openFile = SYS_FileOpen ("c:\mytests\test.log",FM_READ)
// set pointer to 3
iCurrentPos = SYS_FileSetPointer (openFile, 3)
Print (iCurrentPos)
// set pointer to 6 (original 3, plus 3 more)
iCurrentPos = SYS_FileSetPointer (openFile, 3, FP_RELATIVE)
Print (iCurrentPos)
// set pointer 4 characters from end of file
iCurrentPos = SYS_FileSetPointer (openFile, -4, FP_END)
Print (iCurrentPos)
SYS_FileClose (openFile)
// Result: (file has 71 characters)
// 3
// 6
// 67