Sequential Channels¶

Include: Use System\FileSystem.pkg

Sequential input and output commands operate through numbered channels. Channels are numbered 0 through 9.

Use Seq_New_Channel when opening files in application code. It returns an available channel, or DF_SEQ_CHANNEL_NOT_AVAILABLE if none is available. Release the channel with Seq_Release_Channel after closing the file.

Basic pattern¶

Handle hFile

Get Seq_New_Channel to hFile
If (hFile <> DF_SEQ_CHANNEL_NOT_AVAILABLE) Begin
    Direct_Output Channel hFile FILE "test1.txt"
    Write_Line Channel hFile "This is some text."
    Close_Output Channel hFile
    Send Seq_Release_Channel hFile
End

Opening on a channel¶

Direct_Input Channel hFile ..., Direct_Output Channel hFile ..., and Append_Output Channel hFile ... set the current input or output channel and then open the file on that channel.

Get_Current_Input_Channel returns the last active input channel. Get_Current_Output_Channel returns the last active output channel.

Closing channels¶

Close_Input Channel hFile closes that input channel. Close_Output Channel hFile closes that output channel.

The no-channel forms close the current input or output channel:

Close_Input
Close_Output

Use the explicit Channel hFile form in application examples so the matching open, close, and release operations stay together.

Position and size¶

Get_Channel_Position hFile to iPosition returns the current byte position for an open channel. It returns 0 for an unopened or invalid channel.

Set_Channel_Position hFile to iPosition seeks an open channel. It reports a bad channel when the channel is invalid or unopened.

Get_Channel_Size hFile to iSize returns the byte size for an open channel. It reports a bad channel when the channel is invalid or unopened.

Advanced details¶

Seq_New_Channel starts at DF_SEQ_START_CHANNEL, scans upward to but not including DF_SEQ_CHANNEL_MAX, then wraps to the lower reserved channels. It returns DF_SEQ_CHANNEL_NOT_AVAILABLE when none are available.

Seq_Release_Channel releases channel numbers from 0 through 9 for reuse.