Skip to content

Set_Channel_Position

See Also: File I/O Commands, Append_Output, Direct_Input, Direct_Output, Get_Channel_Position, Sequential File I/O

Purpose

To set the input/output channel position pointer to a specific position.

Syntax

set_channel_position channelNum to value

channelNum is the channel number, ranging from 0 through 9.

What It Does

The position pointer for each input/output channel is maintained at the end of the last output (write or writeln) to a file opened by append_output or direct_output, or at the end of the last read (read, read_block, or readln) from a file opened by direct_input.

  • Position 0 is before the first byte in the file.
  • Position 1 is after the last byte.
  • Intermediate positions correspond to the ordinal number of the byte in question.

set_channel_position moves the position pointer for the specified input/output channel to value.

set_channel_position 9 to iCh9Position

In this example, the pointer in input/output Channel 9 is moved to the value of the variable iCh9Position.

If set_channel_position is used to place the pointer within the existing contents, the existing contents will be overwritten by the written material, byte for byte.

To query the position of the pointer for an input/output channel, use the get_channel_position command.

If value is greater than the size of the file, the file will be extended to the indicated size at the time of the next write.

Notes

  • When a file, field, or image has been opened by the direct_input command, its channel position is 0 (the beginning of the file). After an append_output command, it is at the end of the file. A get_channel_position command immediately after an append_output or set_channel_position to -1 statement returns the size of the file.

  • Caution: Unexpected behavior can result from mixing sequential I/O code that uses channels with code that does not. 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.