Get_Channel_Position

Purpose

Gets the value of the file offset of a sequential file channel.

Syntax

Get_Channel_Position {channel-num} To {variable}

Argument Explanation

{channel-num}: A value between 0 and 9, representing the sequential channel. 0 is the default for Direct_Input, and 1 is the default for Direct_Output.
{variable}: A variable into which the number of the channel is returned.

What It Does

The channel position is the offset to the last byte accessed in a sequential file. If a file is opened with Direct_Input, the channel position will return the last byte read by input commands such as Readln. For files opened with Direct_Output or Append_Output, the channel position will return the last byte written by output commands such as Writeln.

Get_Channel_Position can return two values that have a special meaning: - Position 0 is before the first byte in the file. - Position 1 is after the end of the file.

The position can be set to after the end of a file using Set_Channel_Position.

Example

Integer iCount
Integer iPos
String  sBuffer

// Create a text file
Direct_Output "hello.txt"
For iCount From 1 To 10
    Get_Channel_Position 1 To iPos
    Showln "Writing at offset " iPos " in hello.txt"
    Writeln "Line: " iCount " - Hello!"
Loop

Get_Channel_Position 1 To iPos
Close_Output
Showln "Position at end of file in hello.txt is " iPos

// Error returns 0.
Get_Channel_Position 9 To iPos
Showln "Error position is " iPos

// Open file for input.
Direct_Input "hello.txt"
While (Not(Seqeof))
    Get_Channel_Position 0 To iPos
    Showln "Reading at position " iPos " in hello.txt is " iPos
    // Read from the text file.
    Readln sBuffer
Loop
Close_Input

Notes

When a file has been opened by the Direct_Input command, its channel position is zero (0) (the beginning of the file). After an Append_Output command, the position is at the end of the file.
A Get_Channel_Position command immediately after an Append_Output command returns the size of the file.
A Get_Channel_Position on a closed channel will return a zero (0).
To move the pointer for a sequential input/output channel, use the Set_Channel_Position command.
Caution: Unexpected behavior can result from mixing sequential I/O code that uses channels with code that does not, since sequential I/O code that does not use explicit channel numbers will use the default channel or the last channel explicitly specified. We recommend always explicitly using channel numbers.