Open

Opens a disk file for reading or writing using file operations

Syntax
   Open filename For Input [encoding_type] [lock_type] As [#]filenumber
   Open filename For Output [encoding_type] [lock_type] As [#]filenumber
   Open filename For Append [encoding_type] [lock_type] As [#]filenumber

   Open filename For Binary [access_type] [lock_type] As [#]filenumber
   Open filename For Random [access_type] [lock_type] As [#]filenumber [Len 
   = record_length]

Usage
   result = Open( filename[,] For {Input|Output|Append}[,] As filenumber )
      or
   result = Open( filename[,] For Binary[,] Access {Read|Write}[,] As 
   filenumber )
      or
   result = Open( filename[,] For Random[,] Access {Read|Write}[,] As 
   filenumber [[,] Len =  record_length] )
      or
   Open filename For {Input|Output|Append} As filenumber
      or
   Open filename For Binary Access {Read|Write} As filenumber
      or
   Open filename For Random Access {Read|Write} As filenumber [Len =  
   record_length]

Parameters
   filename
      A string value of the name of the disk file to open. Relative file 
      paths are relative to the current directory (see CurDir).
   encoding_type
      The encoding to be used when reading or writing text, can be one of:
         * Encoding "ascii" (ASCII encoding is used, default)
         * Encoding "utf8" (8-bit Unicode encoding is used)
         * Encoding "utf16" (16-bit Unicode encoding is used)
         * Encoding "utf32" (32-bit Unicode encoding  is used)
   access_type
      The type of access requested by the calling process.
         * Access [Read] [Write] (both read and write access can be used, 
           which is the default)
   lock_type
      Imposes restrictions on disk file access from other processes 
      (threads or programs), can be either:
         * Shared (the file can be freely accessed by other processes)
         * Lock [Read] [Write] (both read and write access can be denied 
           to other processes)
   filenumber
      An available file number to bind to the disk file, which can be found 
      with FreeFile.
   record_length
      The size, in bytes, of each record read from or written to the disk 
      file. The default is 128.

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

Description
   Opens a disk file for reading and/or writing. The file number file_num 
   is bound to the file on disk, for use in subsequent file operations, 
   such as Input # and Lock. The next available file number can be 
   retrieved with FreeFile.

   The Input, Output and Append file modes open disk files for sequential 
   text I/O, useful for reading or writing plain text files:
      * When the Input mode is specified, only reading file operations can 
        be used, like Line Input # and Get #. If the disk file does not 
        exist a runtime error will be thrown.
      * The Append mode specifies that only writing operations can be 
        used, like Print # and Put #.  Writing operations will take place 
        at the end of the disk file if it exists, preserving the existing 
        data.
      * The Output mode is like the Append mode, except that if the file 
        exists then its contents are deleted and its length reset to zero 
        before writing.

   The Input, Output and Append file modes also allow selection of a 
   character encoding to be used when reading from or writing text to the 
   disk file. ASCII or a Unicode encoding may be specified (see the 
   description of the encoding_type parameter above).

   The Binary and Random file modes open disk files for random-access 
   reading or writing of arbitrary sized binary data:
      * The Binary file mode allows reading and writing of simple data 
        type values, like Byte or LongInt, using binary read or write 
        operations, like Get #. LOC and Seek are among the procedures used 
        for reading and writing to arbitrary locations in the disk file.
      * The Random file mode is similar to Binary, except that file I/O 
        operations always use a constant data size when reading or writing.

   By default, the Binary and Random file modes allow both reading and 
   writing operations on the opened disk file, but this can be changed by 
   specifying an access type (see the description for the access_type 
   parameter above). When opening an existing file in Binary or Random file 
   mode, and with the only Write access type specified, all data in the 
   file are previously deleted at opening, before any other operation.

   For any file mode, access to the opened disk file can be restricted or 
   granted to other threads or programs by specifying a lock type (see the 
   description for the lock_type parameter above). If no lock type is 
   specified, other threads of the current program can freely open the disk 
   file (Shared), while other programs cannot (Lock Read Write). Lock and 
   Unlock can be used to temporarily restrict access to parts of a file.

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

Example
   ' Create a string and fill it.
   Dim buffer As String, f As Integer
   buffer = "Hello World within a file."

   ' Find the first free file number.
   f = FreeFile

   ' Open the file "file.ext" for binary usage, using the file number "f".
   Open "file.ext" For Binary As #f
   If Err>0 Then Print "Error opening the file":End

   ' Place our string inside the file, using number "f".
   Put #f, , buffer

   ' Close all open files.  
   Close

   ' End the program. (Check the file "file.ext" upon running to see the output.)
   End

   'OPEN A COM PORT
   Open Com "COM1:9600,N,8,1" As #1
   If Err>0 Then Print "The port could not be opened."

   'COM1, 9600 BAUD, NO PARITY BIT, EIGHT DATA BITS, ONE STOP BIT

   'function version of OPEN
   If Open("file.ext" For Binary Access Read As #1) = 0 Then

      Print "Successfully opened file"

      '' ...

      Close #1

   Else

      Print "Error opening file"

   End If

Platform Differences
   * Linux requires the filename case matches the real name of the file. 
     Windows and DOS are case insensitive.
   * Path separators in Linux are forward slashes /. Windows uses backward 
     slashes \ but it allows for forward slashes /.  DOS uses backward 
     slashes \.
   * On Windows, a file number used in a dynamic link library is not the 
     same as an identical file number used in the main program.  File 
     numbers can not be passed or returned and then used between a DLL and 
     an executable.
   * If you try to open a directory on Linux, the Open command will 
     succeed.

Differences from QB
   * Using MS-DOS device names to open streams or hardware devices ("LPT:"
     , "SCR:", etc.) is supported only in the -lang qb dialect; for other 
     modes FreeBASIC's new composite keywords must be used: see Open Com,  
     Open Cons,  Open Err,  Open Pipe,  Open Lpt,  Open Scrn.
   * Open can be called as a function that returns an error code.

Dialect Differences
   * The -lang qb dialect supports the old GW-BASIC-style syntax OPEN 
     mode_string, #filenumber, filename [length] with mode_string being "I" 
     for input, "O" for output, "A" for append, "R" for random, "B" for 
     binary. 

See also
   * Err (and a list of error codes)
   * Close
   * FreeFile
   * Open Cons, Open Err, Open Pipe, Open Lpt, Open Com, Open Scrn

