Getting Started
Sample Programs
Code Snippets

Web Sites
More Tutorials
User Groups
Talk Shows

Progress Bar

GBIC >> PowerBASIC >> Tutorials >> Files

PowerBASIC Information Center Tutorials
These tutorials were written to help you get a quick, but thorough, understanding of PowerBASIC - the scope of the language as well as it's specific capabilities.

Introduction       Projects       Language           Messages       Functions           Advanced
  • Overview
  • Examples
  • IDE
  • Compilation
  • Distribution
  • Project Files
  • DDT Windows
  • Controls
  • Menus
  • Dialogs  
  • Help Files
  • Resources  
  • Templates  
  • Project Shell  
  • Syntax
  • Operators
  • Data Types
  • Variables
  • Scope
  • Declarations  
  • Procedures
  • Flow Control
  • Windows
  • Messages
  • Callbacks
  • Mouse
  • Keyboard
  • Dialogs
  • Controls
  • Subclassing
  • Arithmetic
  • Trig  
  • Strings
  • Arrays
  • Date/Time
  • Printing
  • Files
  • Folders
  • Keyboard
  • Mouse
  • Sound
  • System
  • Error Traps
  • Debugging
  • Objects
  • Graphics
  • Databases
  • API
  • DLLs
  • ASM
  • Threads
  • Files
    PowerBASIC offers several functions that deal with files, as summarized in the following categories.

      • Access Control    
       lock, unlock 
      • File Access
       open, close, freefile,
      filename$, isfile
      • File Management
       kill, name, setEOF 
      • Write To File
       write#, print#, flush 
      • Read From File
       input#, line input# 
      • Random/Binary Files
       get, get$, put, put$, 
      loc, seek, field
      • Opened File Information
       eof, lof, fileattr, filescan 
      • Closed File Information
       getattr, setattr 
      • Utilities
       pathname$, pathscan$, filecopy 
      • Program Data
       data, read$, datacount 

    File Basics
    In order to read or write information from/to a file, the file must first be opened, using the Open command. There are five modes in which a file may be opened - input, output, append, random and binary. The input, output and append modes are called sequential mode because a read/write can only take place right after the last read/write. For random/binary modes, file read/write operations can take place at any location within the file.

    Here's an example of opening a file in each of the five modes.

        open "myfile.txt" for input  as #1          ' read only
        open "myfile.txt" for output as #1          ' write only, erases content
        open "myfile.txt" for append as #1          ' write only, at end of file
        open "myfile.txt" for random as #1 len=80   ' fixed length lines
        open "myfile.txt" for binary as #1          ' byte-level read/write

    File Content
    Files generally come in two flavors - binary and text files, with a couple of variations of text files.

    • Text Files - Variable Line Lengths
      Text files typically consist of lines of text separated by a carriage return/line feed (CR/LF) pair of characters. The lines are typically, but not necessarily, of different lengths.

    • Text Files - Fixed-Length Lines
      Other text files contain lines which are all exactly the same length but may or may not be separated by the CRLF character pair. Fixed-length text files are often used a databases, where each line of text is called a record and each record is broken into smaller fields of information.

    • Binary Files
      With binary files, there are no lines at all. Information may be an apparently random combination of text and binary data.

      Binary data is simply non-text code, where the bytes of data do not interpret into the familiar ASCII text characters. Numeric values, machine language, and individual bit flags are some of the types of content that make up binary data - all of unreadable by human eyes.

    PowerBASIC file statements and functions specifically work with these three kinds of file content. Opening, reading, writing, and closing are the basic capabilities - with a few dozen supporting features to make the task as easy as possible.

    File Modes
    To read from or write to a file it must first be "opened", which simply means that a file's read/write options are defined and the application locks the file for its (usually) exclusive use. When the file is closed it is unlocked and available for other applications to use.

    In PowerBASIC there are five modes in which a file may be opened. They affect how the file may be read or edited.

    • Input
      Opens an existing file as read-only. The file is read front-to-back, with the current position set to the first byte of the file.

    • Output
      Create a new file as write-only. If the file already exists, the content is first deleted. The current position is set to the first byte of the now empty file.

    • Append
      Opens an existing file as write-only. The content of the file is unchanged and the current position is set to the end of the file - one position past the last byte in the file, so that the next write/print appends the information to the existing content of the file.

    • Random Access
      Opens an existing file for reading or writing. This type of file typically contain lines of fixed lengths, as discussed in the examples above. The file is read or written a line at a time, where each line typically consists of multiple, smaller fields of information.

      Because all lines are of equal length and the start/end of each line is know, it is possible to randomly read or write any record.

    • Binary
      Opens an existing file for reading or writing. Information does not consist of lines or records, but does generally contain string or numeric data. All read/write operations treat the content simply as bytes of data and it is up to the programmer to convert the data to the appropriate string or numeric content.

      In particular, numeric data is written in the same format as it is stored in memory - without converting it to a string series of ASCII characters. The numbers may be any of the data types supported by PowerBASIC, integer, floating-point numbers, etc., each of which are represented by a unique format and number of bytes in memory.

      Bytes can be randomly read or written.

    Closing a File
    When a program complete all read/write operations on a file, it closes the file, which releases it for use by other applications. When a PowerBASIC program ends, PowerBASIC automatically closes all files. However a file can also be explicitly closed within the program. Files can even be opened/closed in different modes as many times as needed during the execution of a program.

    Reading From Files
    In PowerBASIC there are three basic statements which read from a file. These differ primarily in how much data is read - a variable, a list of variables, a specific number of bytes, or entire lines and records.

    • input# - reads variable(s) from a file
    • line input# - reads an entire line from a file into a variable
    • get - read a byte(s) or record into a variable(s)

    Writing to a File
    There are three functions which provide the ability to write to files. These differ primarily on how the data is written - as text or binary data.

    • print# - writes variable(s) using default text formatting
    • write# - writes variables using CSV text formatting
    • put - writes variable(s) or a record to a specific location

    Complementary Read/Write Statements
    The read/write statements above can be grouped into the following complementary pairs - where a read statement can access information placed in the file by a write statement.

    • Print#, Line Input# - sequential files
    • Write#, Input# - sequential files
    • Get/Put - random access / binary files
    • Get$/Put$ - binary files

    These are discussed in more detail below, but this overview helps understand where the statements are useful.

    Line Input#, Print#
    These two functions are complementary sequential file functions. Line Input# reads an entire line and places it into a variable. The Print# statements writes one or more variables to a file in text format.

    The programmer must manage the inclusion of CRLF characters to start/end lines of data.

    These may be the most used file read/write functions. Text files are very popular with programmers because the content can be edited by simple text editors. This provides a level of security against file corruption.

    For working with random access and binary files, PowerBASIC provides the Get/Put statements.

    Get reads a record from a random access file. It reads a variable or array from a binary file.

    Put writes a record to a random access file. It writes a variable(s) or array(s) to a binary file

    Read/write actions take place at the current pointer position, which can be changed using SEEK. File size may grow if the pointer position if set beyond the EOF.

    Get/Put can work with standard text files, but their strength is in dealing with random access and binary files.

    These are also very popular, particularly because of the ease with which large amounts of data can be written with minimal code.

    Input#, Write#
    These two functions are also complementary sequential file functions. Write# puts data in a file that Input# can read. The format is the industry standard comma separated values (CSV).

    Write# puts data in a file, enclosed by quotes (strings) and separated by commas. Each Write# statement also writes a CR/LF at the end of the data.

        Write#1, "he", "be"      '"he","be" on a line by itself
        Input#1, a$, b$          ' reads "he" and "be"

    These statements are not as popular, but since the CSV output is an industry standard and the data files can be read by other programs (such as Microsoft Excel), it continues to have loyal followers.

    Essentially simpler versions of Get/Put, the Get$/Put$ statements are an easier way to deal with data at the byte level. These are limited to working with files opened in binary mode only.

    Get$ reads a specific number of bytes (characters) and Put$ writes a specific number of bytes (characters).

        Get$ #1, n&, s$       'get n& bytes and put in variable s$
        Put$ #1, s$           'put s$ (however many bytes there are)

    Read/write actions take place at the current pointer position, which can be changed using SEEK. File size may grow if variable size causes Put$ to write beyond EOF.

    The popularity of these statements is similar to that of the Get/Put statements. Programmers readily switch between the simpler Get$/Put$ and more powerful Get/Put statements.

    Special Array Support
    Programmers like to work with arrays, particularly when dealing with files, because of the convenience in writing many elements with a single statement. The following PowerBASIC statements provide special syntax to deal with handling arrays.

    Here is a one-line description of the file functions which support reading/writing/creating arrays. More information on each is provided in the reference listing at the bottom of this page.

    • LINE INPUT# - read lines into string array (sequential file)
    • GET - read array (binary file)
    • PRINT# - write array (sequential file)
    • PUT - write array to binary file

    When dealing with sequential files, a text file can be read into an array, with one line of text per array element. Or, a string array can be written to a file with one array element per line.

    When dealing with binary files, an array variable can be read or written with a single line of code.

    These statements perform other read/write operations as well, but this section focused on just the array handling features.

    File Position
    PowerBASIC can track, or set, the current position in a file, which is where the next read or write will take place. The two functions that provide file positional information are:

    • loc - identifies the current position within a file
    • seek - set/return current file position

    PowerBASIC discourages the use of Loc in favor of the newer Seek function.

    DATA Statements
    PowerBASIC provides the DATA statement, which allows values to be stored as part of a program's source code. When the program is executed the values can be read into string variables with the READ$ statement.

    In the following example, five DATA statements, each with five values, are shown along with the code to read all 25 values.

        DATA 1,1,4,1,1             For y% = 1 to 5
        DATA 1,1,4,1,1                For x% = 1 to 5
        DATA 4,4,4,4,4                    incr n% : z$ = READ$(n%)
        DATA 1,1,4,1,1                next x%
        DATA 1,1,4,1,1             next y%

    This example might represent a 5x5 matrix of color values for creating a sprite. So while all 25 values could be stored in a single DATA statement, the five DATA statements actually provide a visual preview of the sprite shape.

    The READ$ function gets a single value from the first DATA statement and places the value into a variable, starting with the first DATA statement in the program. Each successive READ$ gets the next DATA value, skipping to the next DATA statement once all values in the current DATA statement are read.

    Each procedure in a PowerBASIC program can have its own set of DATA statements, with up to 64KB and 16,384 values.

    File Functions Listing
    Here's a simple listing of the file functions above, with a one-line description of what the function does. Syntax and examples are given in the next section.

    • CLOSE - close an opened file
    • EOF - determine if read position is at end of the file
    • FIELD - bind variable to random file buffer or dynamic string variable
    • FIELD RESET - set FIELD string to nul (zero-length dynamic string)
    • FIELD STRING - change FIELD string to a dynamic string, fill with current data
    • FILEATTR - get information about an open file
    • FILECOPY - copy a file
    • FILENAME$ - get filename of a specified open file
    • FILESCAN - get file info by quickly reading INPUT/BINARY file
    • FLUSH - write file buffer content to disk
    • FREEFILE - get next available file number
    • GET - read record from file (random-access mode)
    • GET$ - read string from a file (binary mode)
    • GETATTR - get attributes of a file/folder
    • INPUT# - read data from sequential file (to variables)
    • ISFILE - determine if a file exists
    • KILL - delete a file
    • LINE INPUT# - read line from sequential file (to variables)
    • LOC - get current position in open file
    • LOCK - lock part/all of an open file
    • LOF - get length of open file
    • NAME - rename file/folder
    • OPEN - open a file for reading/writing
    • PATHNAME$ - extract components from pathname
    • PATHSCAN$ - search for a file, including subdirectories
    • PRINT# - write to sequential file
    • PUT - write record to random-access file or variable to binary file
    • PUT$ - write string to file (binary mode)
    • SEEK - set/return position in file for next I/O operation
    • SETATTR - set file/folder attributes
    • SETEOF - truncate/extend file to file pointer position
    • UNLOCK - remove lock on file
    • WRITE# - write data to sequential file in a delimited format

    File Functions Reference
    Here are examples for each of the file functions. The functions are listed in alphabetical order.

    • close - closes one, several or all open files or devices
          close #1        ' closes a single file
          close #2, #3    ' closes two open files
          close           ' closes all open files
      The # symbol is optional. Buffers are flushed. Works with files and devices.

    • data - specifies data for subsequent read statements
          data "ab", "rs"            ' strings, no quotes
          data 1, 4, 5, 7            ' numbers, but read as strings
          data "a b", " rs"          ' strings

      Each procedure has its own DATA statements. Quotes only needed if leading/trailing spaces are to be included in the values.

    • datacount - returns number of local DATA values
          n% = DATACOUNT

      Use to set the bounds of a For/Next loop to read all values.

    • eof - determine if read/write position is at end of open file
          result% =  eof(1)      ' -1 end of file, 0 not end of file
          result% =  eof(#1)     ' # is optional
          if eof(1) then
              'eof has been reached
          end if

      Must use valid file number. Works on binary file only if last operation was unsuccessful read.

    • field - allocates space for variables in a random-access file buffer
          field #1, width% AS var$        ' string variables only
          field #1, 30 as a$, 50 as b$    ' multiple variables supported

    • fileattr - get information about open file
          result&  = fileattr(#1,1)     ' file mode
          result&  = fileattr(#1,0)     ' open status
          Return Options:    
          -3 device type (1-file, 2-device)
          -2 logical first byte (base) position of file
          -1 minimum read data Random-->record length, 
                               Input-->LEN value,
           0 open state. -1 true, 0 false
           1 file mode 1-input, 2-output, 4-random, 8-append, 
                 16-comm, 32-binary, 64-TCP, 128-UDP
                 combinations allowed - Append = 8+2 = 10
           2 file handle. can use with PowerBASIC OPEN HANDLE statement
           3 enumerates existing file numbers. 1st # - FILEATTR(1,3)
                 2nd # - FILEATTR(2,3), etc. -1 if no more file numbers.

    • filecopy - copy a file
          FILECOPY "c:\data\test.txt", "c:\data\text.bak"    ' from,to

      Both arguments include a file name. Neither can contain just a path. Wildcards cannot be used. The destination file will be overwritten, unless it is read-only or locked (causes run-time error).

    • filename$s - get filename of an open file
          f$ = filename$(#1)       ' returns name of open file #1

      Not valid with OPEN HANDLE, COMM/TCP/UDP OPEN.

    • filescan - get record count and max line length
          filescan #1, RECORDS TO linecount&, WIDTH to maxwidth&

      INPUT/BINARY mode only.

      Input mode - assumes CR/LF line delimiter. Stops at Chr$(26) or end of file. Last line counted even if doesn't end in CR/LF.

    • flush - write file buffer content to disk
          flush #1, #2        'write buffers to disk, # is optional
          flush               'flush all files

    • freefile - returns the next valid unused file number
          open "myfile.txt" for output as freefile   ' use directly
          result% = freefile           ' get next valid file number

      freefile is used to ensure that a program does not try to open a file with an already used number, which would cause a program error.

      returns new number with each invocation, regardless if last number from last call was used to open a file.

    • get - reads from a file into a variable
          get #1, recordnumber&, variable     ' random-access mode
          get #1, bytelocation&, variable     ' binary mode
          get #1, 25, var$    'gets 25th record
          get #1,5,rec$       'random access file - record 5
          get #1,4,n%         'binary file - variable starting at byte 4
                                           - bytes read = length of variable
          get #1,87,myarray$  'binary file - array starting at byte 87
          get$ #1,42          'binary file - read 42 strings, starting at pos

    • getattr - get file/directory attributes
          result& = GETATTR("c:\data\test.txt")
          result& = GETATTR("c:\data\")
      result& is OR'd combination of the following Attribute Codes:
          0 or 128  Normal        %NORMAL
          1         Read-only     %READONLY
          2         Hidden        %HIDDEN
          4         System        %SYSTEM
          8         Volume Label  %VLABEL
          16        Directory     %SUBDIR
          32        Archived      %ARCHIVE 
      Use AND to test for specific attribute.
          If (result& AND  1&) =  1 Then ...   READONLY attribute set
          If (result& AND  2&) =  2 Then ...   HIDDEN   attribute set
          If (result& AND  4&) =  4 Then ...   SYSTEM   attribute set
          If (result& AND  8&) =  8 Then ...   VLABEL   attribute set
          If (result& AND 16&) = 16 Then ...   SUBDIR   attribute set
          If (result& AND 32&) = 32 Then ...   ARCHIVE  attribute set
      File must exist! Does not work on "c:\" (root directory). Full pathname not required.

    • input# - reads variables from sequential file
          input #1, a%, b%        ' input list of variables from 

      Data in file must be comma separated, with CR at end of line (Write# creates this format).

    • isfile - checks to see if file exists
          result$ = ISFILE ("c:\data\test.txt")   ' -1 found, 0 not found

      All attributes accepted (hidden, system, read-only, ...)

    • kill - delete a file
          kill "c:\temp\test.bat"    ' deletes test.bat
          kill "test.bat"            ' deletes test.bat in current directory
          kill "*.bas"               ' wildcards allowed

      Fill must exist! Can include wildcard. Path can be included. Does not use Windows trashcan. Request to kill HIDDEN/SYSTEM files is ignored. Does not work on folders.

    • line input# - reads a line of up to 255 characters from keyboard or file
          line input ; "prompt" ; var$       ' input from keyboard
          line input #1, var$                ' input from open file

      Note: line input# expects lines to be separated by the line feed/carriage return character pair. If no such pair exists, the entire file will be read into the variable (up to the PowerBASIC 32K string length limit).

    • loc - returns current position within a file
          result&& = loc(#1)     

      Use of SEEK is recommended over LOC

    • lof - get length of open file
          result&& = LOF(1)            ' bytes
          result&& = LOF(#1)           ' # is optional

    • lock - controls access to file by other processes
          lock #1      ' locks entire file (INPUT, OUTPUT, APPEND)
          open "myfile.txt" for random as #1
          lock #1, 25               ' locks only record 25
          lock #1, 25 TO 40         ' locks records 25-40
          open "myfile.txt" for binary as #1
          lock #1, 25               ' locks 25th byte
          lock #1, 25 TO 40         ' locks bytes 25-40

      Binary - byte level locking. BASE clause in OPEN statement determines how byte entries are applied.

      Random - record level locking.

      Sequential files -locking of entire file.

      Locked file must be Unlocked before the file can be closed.

    • lof - returns length of open file (in bytes)
          open "myfile.txt" for input
          result = lof(1)

    • name - renames a file or directory
          name "myfile.txt" As "newfile.txt"        ' renames a file
          name "c:\test.bat" As "c:\temp\temp.bat"  ' rename/move file

      File must exist! File cannot be opened or locked. Full path allowed. If target file exists, error occurs. Wild cards not permitted.

      Can use to move file to new directory (cannot move directories).

    • open - open a file for reading/writing
          open file$ for mode$  ACCESS  LOCK  as #1 len=reclen%  ' syntax
             ' file$ can be filename or device
             ' modes: append, binary, input, output, or random
             ' lock types: shared, lock read, lock write, lock read write
             ' default record length for random-access files is 128 bytes
             ' default record length for sequential files is 512 bytes
          open "myfile" for input  as #1
          open "myfile" for output as #1
          open "myfile" for append as #1
          open "myfile" for binary as #1 
          open "myfile" for random as #1 len=80

      Must use unique file number.

      INPUT file must exist! If not exist, all other modes will create the file.

      Access (this process): Read, Write, ReadWrite

      Lock (other processes): LockShared, LockWrite, LockRead, LockReadWrite

      LEN for random access (default 128). Also to define sequential access buffer.

      BASE for random access only (sets first byes as 0 or 1)

    • pathname$ - extracts specific parts of pathname
          f$ = "c:\data\text.txt"         ' does not have to exist
          result$ = PATHNAME$(FULL, f$)   ' c:\data\text.txt
          result$ = PATHNAME$(PATH, f$)   ' c:\data\
          result$ = PATHNAME$(NAME, f$)   ' text
          result$ = PATHNAME$(EXTN, f$)   ' .txt  (includes period)
          result$ = PATHNAME$(NAMEX, f$)  ' text.txt

    • pathscan$ - finds a file, returns specific part of filespec.
          f$ = "text.txt"            ' file to find. no wildcards!
          d$ = "c:\data"             ' folder to search    
          d$ = "c:\data;d:\info"     ' 
          PATHSCAN$(FULL, f$, d$)    '
          PATHSCAN$(PATH, f$, d$)    '
          PATHSCAN$(NAME, f$, d$)    '
          PATHSCAN$(EXTN, f$, d$)    '
          PATHSCAN$(NAMEX, f$, d$)   '
          Default search paths:   application folder
                                  current folder
                                  folders in PATH environment 

      Returns "" if file not found. Multiple paths, separated by semicolons, are allowed. Path is optional. If path not given, or is "", then default search paths are used. Multiple search paths are allowed, separated by semicolons.

    • print# - writes data to screen or file
          print #1, varlist ;         ' prints to a file
          print varlist               ' prints to screen

      Semicolon at end means print immediately after last value. A comma would mean print at end of print zone (14 char wide). No value means print on next cursor line.

    • put - writes a variable to a file
          put #1, recordnumber&, variable     ' random-access mode
          put #1, bytelocation&, variable     ' binary mode
          open "myfile.txt" for binary as #1
          put #1, 25, var$                    ' puts 25th byte
          open "myfile.txt" for random as #1 len=40
          put #1, 25, var$                    ' puts 25th record
          put$ #1, var$                       ' puts var at current pos

    • read$ - reads values from DATA statements
          data "one", "two", "three"    ' data statement with values
          a$ = read$(1)                 ' reads 1st value
          a$ = read$(2)                 ' reads 2nd value

      If index > DATACOUNT, read$ returns "" (no error). If values are enclosed in quotes, leading/trailing spaces are preserved. Can only read DATA statements within current procedure.

    • seek - returns or sets the position in a file
          result&& = seek(#1)   ' returns position in file #1, # is optional
                                ' random access - next record to write
                                ' all other modes - next byte to read/write
          seek(#1,124)          ' set file position to 124, # is optional
                                ' random access - next record to write
                                ' all other modes - next byte to read/write

      When using seek, the BASE setting, which specifies the position of the first byte/record as 0 or 1, must be taken into account.

    • setattr - set file/folder attributes
          SETATTR("c:\data\test.txt", %HIDDEN)    
          SETATTR("c:\data\test.txt", %READONLY)
      Allow attributes are:
          0     Normal        %NORMAL
          1     Read-only     %READONLY
          2     Hidden        %HIDDEN
          4     System        %SYSTEM
          32    Archived      %ARCHIVE 
      File must exist! Does not work on "c:\" (root directory). Full pathname not required. With attribute 0 - file is not read-only, not hidden, not system and not archived.

    • seteof - truncate file to current file pointer position
          seteof #1        ' #1 is an open file
          seteof 5         ' # is optional

      Works on open file only. Truncates at current position. Can also set position explicitly with SEEK.

    • unlock - remove lock on file
          unlock #1      ' unlocks entire file
          open "myfile.txt" for random as #1
          unlock #1, 25               ' unlocks only record 25
          unlock #1, 25 TO 40         ' unlocks records 25-40
          open "myfile.txt" for binary as #1
          unlock #1, 25            ' unlocks 25th byte
          unlock #1, 25 TO 40         ' unlocks bytes 25-40

      For binary/random files, restores access to range of records or bytes. BASE clause in OPEN statement determines how byte entries are applied.

      For sequential files, affects the entire file (no by-record or by-byte control).

      Locked file must be Unlocked before the file can be closed.

    • write# - writes data to screen or file
          write #1, "hello"      
          write #1, a$, b$, c$

      Strings are written in parentheses and all variables are separated by commas. A CRLF is written after the last variable.

      Ending the variable list with ; replaces the CRLF with a comma, which allows writing additional data to the same line of text.

    If you have any suggestions or corrections, please let me know.