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
• 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
• 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.

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

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.

Get/Put
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.

Get$/Put$
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,
Binary/Output/Append-->1)
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
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
' 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.

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
Windows32
Windows16
Windows
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)

Allow attributes are:
    0     Normal        %NORMAL
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.