Direct_Input

Purpose

To open a file or device for sequential input.

Syntax

General syntax:

Direct_Input [Channel {ChannelNumber} {FileMode}: {FileModeOption}] {driver} {file/device}

For sequential file input:

Direct_Input [Channel {ChannelNumber} {FileMode}: {FileModeOption}] {FileName}

For Windows clipboard input:

Direct_Input [Channel {ChannelNumber} {FileMode}: {FileModeOption}] "clipboard:"

Where

{FileName} is a string with any valid file name.
{ChannelNumber} may be 0 through 9, and if omitted, will be assumed to be 0 (default for input) or the last channel number explicitly specified in code executed previously.
Only {FileName} and {ChannelNumber} may be contained in variables; the term Channel must be hard-coded. The colons are required as shown after each element and each value.

File Modes:

{FileMode} may be either binary: or pc-text:. If omitted, it will be pc-text:.
{FileModeOption} may be any or all of:
cr: AsciiValue (defaults: binary: -1, pc-text: 13)
eol: AsciiValue (defaults: binary: 10, pc-text: 10)
eof: AsciiValue (defaults: binary: -1, pc-text: 26)
width: bytes (default: 2048)

AsciiValue -1 means not used (no value). If any {FileModeOption} is omitted, its default AsciiValue or bytes will depend on the mode.

Drivers:

[driver:] {file/device} may be: - file: FileName - dir: [fileSpec] (default is *.*) - clipboard: (the Windows clipboard) - direct: FileName - resource: ResourceName or ResourceID

If the driver is omitted, it will be file:.

What It Does

The Direct_Input command opens sequential files for input. Use the Read, Read_Block, or Readln commands to read the data from the file.

A sequential file is generally opened at the beginning of the file. Use the Set_Channel_Position command to change the point from which data will be read. Get_Channel_Position returns the current position of the input channel.

Example

The following example shows a function method that calculates how many lines are in a sequential file.

Function LineCount String sFilename Returns Integer
    Integer iLineCount
    String sBuffer
    // Look for an available sequential file channel.
    // Use ReadLn to check that file is not already open.
    ReadLn Channel 9 sBuffer
    If (Seqeof) Begin
        // If we have an available sequential file channel.
        Send Stop_Box "Error!" "Cannot open file. Channel 9 is busy."
        Function_Return 0  // Cannot open file
    End
    Else Begin
        Direct_Input Channel 9 sFilename
        If (Not(Seqeof)) Begin   // File exists.
            Showln "File " sFilename " is open on channel 9."
            Move 0 to iLineCount
            ReadLn sBuffer
            While (Not(Seqeof))
                Increment iLineCount
                ReadLn Channel 9 sBuffer
            Loop
        End
        Close_Input Channel 9
        Function_Return iLineCount
    End
End_Function

Example

The following example reads the contents of the clipboard and shows them on the screen:

String sBuffer
Direct_Input "Clipboard:"
Showln "Contents of Clipboard"
While (Not (Seqeof))
    // Read from the clipboard
    Readln sBuffer
    Showln sBuffer
Loop
Close_Input

Working with UChar Arrays

Read_Block can receive the data in a UChar array. This can be used in place of a string variable and has the advantage that you don't have to worry about maximum string size and you don't have to concern yourself with embedded zeros.

Procedure ReadFromPDFFile String sInputFile
    UChar[] PDFManual
    // read a sequential file
    Direct_Input Channel 5 ("Binary:" + sInputFile)
    If (SeqEOF) Begin
        Procedure_Return
    End
    // read entire file into UChar array
    Read_Block Channel 5 PDFManual -1
    Close_Input Channel 5
    // write this to my table
    Set_Field_Value Product.PdfManual (RefTable(Product)) to PDFManual
End_Procedure

Drivers

Various drivers permit input in different formats from different types of files and devices. If no driver is named, the file: driver is used. This driver is suitable for input from a sequential file. The desired file must be named in FileName, complete with path, if desired. If DataFlex buffering of file input is not desired, the direct: driver may be substituted.

Example

Direct_Input "direct: com2:"

In this example, channel 0 (or the last previously accessed channel) is defined to take input without DataFlex buffering from Device com2:.

Input from the clipboard: device is from the Windows clipboard. The contents of the clipboard may be accessed the same as for any text file—it can be read from via read... statements in a loop until the seqeof predefined indicator is true.

An operating-system folder may be opened like a file with the dir: [fileSpec] driver. If fileSpec is omitted, the value of *.* (all files) will be assumed. Once the folder has been opened, it may be read from, line by line, with readln commands. Readln loops terminating when predefined indicator seqeof becomes true will read in the entire folder.

Example

String sLine
Direct_Input "dir: c:\program files\DataFlex"
Repeat
    Readln sLine
    Showln sLine
Until (Seqeof)

This example would display a list of all contents of the "C:\Program Files\DataFlex" folder. The output would probably look something like this:

[.]
[..]
[Bin]
[Bitmaps]
[Documentation]
[Examples]
[Help]
[Lib]
[Pkg]
[Projects]
[Usr]
DataFlex License.rtf
DataFlex ReadMe.rtf

File Modes

For file input, three modes are available, along with options for the Carriage Return (cr:), End of Line (eol:), and End of File (eof:) characters, and maximum argument width.

The pc-text: (default) mode provides default values for cr:, eol:, and eof:. Cr: is set to ASCII 13, eol: to 10, and eof: to 26. The binary: mode, intended for (non-text) files, sets both cr: and eof: invalid, and eol: to 10. Any mode name must be followed by a colon (:).

cr:, eol:, eof:, and width: can be specified in separate options, but it is recommended that such options be given after any mode specifications, since the mode specifications may override the options. If the keywords cr:, eol:, eof:, or width: are included followed by the desired AsciiValue or (for width:) bytes, the parameter will be reset. The value -1 may be used to specify no character for cr:, eol:, or eof:. A colon (:) must be used after each AsciiValue or bytes.

Example

String sMergeFile sFileName
Move "florPlan.pcx" to sMergeFile
Move ("PC-TEXT:" + "EOF: -1:" + sMergeFile) to sFileName
Direct_Input sFileName

In this example, florPlan.pcx is moved to String Variable sMergeFile. Then, an append is done on the strings pc-text:, eof: -1:, and the value of sMergeFile to Variable sFileName. Finally, input through channel 0 is directed from File florPlan.pcx in the pc-text: format with the end-of-file character stripped, through the value of sFileName.

Notes

If you use the Direct_Input command to open a file that is not found, SeqEOF is set true. If the {FileName} in the Direct_Input command is "", SeqEOF will be set to False.
When a Direct_Input command is used on an open channel, the open file is closed, and the new file, {FileName}, is opened.
When Direct_Input is issued when a different source is already open for input, the old source is closed, and the new source is opened.
Certain devices, such as bar-code readers, require unbuffered input. For such devices, use the direct: driver. Using Direct_Input to work with serial devices is very limited. Use FlexCOM for more advanced reading from devices such as serial communication ports.
When two or more output destinations or input sources need to be open at the same time, use the channel {ChannelNumber} option to open additional channels.
Using Direct_Input with the Channel {ChannelNumber} component, but without a device name causes the current input channel number to change to the mentioned channel, and does not close the previously opened device on that channel. This technique is useful when the channel dependent variables (such as SeqEOF) need to be processed.

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.

Example

Direct_Input Channel 1 "MyFile.Txt"
// Now the current input channel is 1
Direct_Input Channel 2 "MyOtherFile.Txt"
// Now the current input channel is 2
Direct_Input Channel 1
// Now the current input channel is 1 again

The Direct_Input command can also be used for reading text lines from the Windows clipboard.