Seq_New_Channel

See Also: File I/O Functions, Seq_Release_Channel, Append_Output, Close_Input, Close_Output, Direct_Input, Direct_Output, Sequential File I/O

Purpose

Retrieves the next available sequential input/output (I/O) channel in an organized way. Specifying a channel number without these management functions can result in a collision. Open output can be closed without wanting to do so explicitly.

Return Type

Integer

Syntax

Use seq_chnl.pkg
(Seq_New_Channel())

Example

Use seq_chnl.pkg
Integer iChannel
Move (Seq_New_Channel()) to iChannel
// ...do some sequential I/O work...
Send Seq_Release_Channel iChannel

Procedure ChannelExample
    Integer iChIn iChOut
    String sFileIn sFileOut sLineIn

    // specify the original (input) file name
    Move "c:\testfile.txt" to sFileIn
    // specify the new (output) file name
    Move "c:\newfile.txt" to sFileOut

    // obtain 2 open channels, 1 for input, 1 for output
    Move (Seq_New_Channel()) to iChIn
    // no channel available
    If (iChIn = DF_SEQ_CHANNEL_NOT_AVAILABLE) begin
        Send Info_Box "No Channel Available for Process" "Error"
        Procedure_Return
    End

    Move (Seq_New_Channel()) to iChOut
    // no channel available
    If (iChOut = DF_SEQ_CHANNEL_NOT_AVAILABLE) begin
        Send Info_Box "No Channel Available for Process" "Error"
        // if iChIn contains a valid channel, release it
        If ((iChIn >= DF_SEQ_CHANNEL_MIN) AND (iChIn <= DF_SEQ_CHANNEL_MAX)) ;
            Send Seq_Release_Channel iChIn
        Procedure_Return
    End

    // at this time both iChIn and iChOut contain a valid value
    Direct_Input Channel iChIn sFileIn  // open input channel
    Direct_Output Channel iChOut sFileOut  // open output channel

    Repeat
        // read a line from input file
        Readln Channel iChIn sLineIn
        If (not (SeqEOF)) begin
            // write the line to output file
            Writeln Channel iChOut sLineIn
        End
    Until (SeqEOF)  // until sequential end of file

    Close_Input Channel iChIn  // close input channel
    Close_Output Channel iChOut  // close output channel

    // release both channels for reuse
    Send Seq_Release_Channel iChIn
    Send Seq_Release_Channel iChOut
End_Procedure

Notes

The Seq_New_Channel function can return a number of predefined constants:

• DF_SEQ_CHANNEL_MIN (predefined value = 0)
  The returned channel number must be a minimum of this value to be a valid channel.

• DF_SEQ_CHANNEL_MAX (predefined value = 9)
  The returned channel number must be a maximum of this value to be a valid channel.

• DF_SEQ_START_CHANNEL (predefined value = 2)
  The default channels for sequential input and output operations are 0 and 1 when not using channels. Thus, the Seq_New_Channel function will start looking for available channels at 2 and use 0 and 1 last.

• DF_SEQ_CHANNEL_NOT_AVAILABLE (predefined value = -2)
  This value will be returned if no channel is currently available for sequential input and output operations.

Valid channel numbers are DF_SEQ_CHANNEL_MIN through DF_SEQ_CHANNEL_MAX. The first returned channel number will be 2 because the channel numbers 0 and 1 are the default channels for direct_input and direct_output to operate on. When the function is called over 8 times, the numbers 0 and 1 will be returned.

If no channel is available, the return value of this function will be DF_SEQ_CHANNEL_NOT_AVAILABLE. This function should be used to find an available I/O channel for use in sequential input and output operations. Usually, this means that either the channel management is used incorrectly or that you want to use too many I/O channels at one time.

The function does NOT open the I/O channel for you. That must be done with a direct_input, direct_output, or an append_output command.

Using this management function can only be successful when applied in all cases in a program.