Open Pipe

Opens an external process' standard input (stdin) or output (stdout) stream 
for file operations.

Syntax
   Open Pipe shell_command For Input As [#]filenumber
   Open Pipe shell_command For Output As [#]filenumber
   Open Pipe shell_command For Binary access_type [#]filenumber

Usage
   result = Open Pipe( command[,] For {Input|Output}[,] As filenumber )
      or,
   result = Open Pipe( command[,] For Binary[,] access_type[,] As 
   filenumber )
      (or in the QB-like syntax,)
   Open Pipe filename For {Input|Output} As filenumber
      (or,)
   Open Pipe filename For Binary access_type As filenumber

Parameters
   shell_command
      The external process to execute in the operating system command 
      shell. Relative file paths are relative to the current directory (see 
      CurDir).  When opening a pipe for a process that requires double 
      quotes in either its executable path, or its arguments, the entire 
      pipe string should be nested inside of double quotes.
   access_type
      The type of read or write access requested by the calling process.
         * Access {Read|Write} (either the stdin or stdout stream of the 
           external process can be opened)
   filenumber
      An available file number to bind to the external process' stdin or 
      stdout stream.

Return Value
   In the first usage, Open Pipe() returns a 32 bit Long: a zero (0) on 
   success and a non-zero error code otherwise.

Description
   Open Pipe executes another process in the command shell and opens either 
   its stdin or stdout streams for reading or writing. A file number is 
   bound to the stream, which is used in subsequent file operations, such 
   as Input #. An available filenumber can be retrieved with FreeFile. If 
   the external process does not exist, a runtime error is thrown.

   The Input and Output file modes open the external process' stdin and 
   stdout streams, respectively, for sequential text I/O, useful for 
   reading or writing plain text. Characters, words or whole lines can then 
   be read or written using text-mode file operations, such as Line Input # 
   and Print #.

   The Binary file mode opens the external process' stdin or stdout streams 
   - depending on the access type specified (see description of the 
   access_type parameter above) - for random-access reading or writing of 
   arbitrarily sized and interpreted raw data. Simple data type values, 
   like Byte and LongInt, and whole chunks of memory can be read from or 
   written to the streams with binary-mode file operations like Get # and 
   Put #.
   Bidirectional pipes are not supported by FB and must be implemented 
   using the OS' API functions.

   The error code returned by Open Pipe can be checked using Err in the 
   next line. The function version of  Open Pipe returns directly the error 
   code as a 32 bit Long.

Runtime errors:
   Open Pipe throws one of the following runtime errors:

   (1) Illegal function call
      * filenumber was not free at the time. use FreeFile to ensure that 
        filenumber is free.

Example
   '' This example uses Open Pipe to run a shell command and retrieve its output. 
   #ifdef __FB_UNIX__
   Const TEST_COMMAND = "ls *"
   #else
   Const TEST_COMMAND = "dir *.*"
   #endif

   Open Pipe TEST_COMMAND For Input As #1

   Dim As String ln
   Do Until EOF(1)
      Line Input #1, ln
      Print ln
   Loop

   Close #1

Platform Differences
   * The Binary file mode is not supported on all platforms; Open Pipe 
     will throw an error if it is unable to open the external process' 
     stdin or stdout streams in binary mode.

Differences from QB
   * New to FreeBASIC

See also
   * Shell
   * Open
   * Open Cons
   * Open Err
   * FreeFile

