Files
PowerBASIC offers several functions that deal with files, as summarized in the following categories.

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.

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.

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.

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.

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.

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.

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:

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.

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

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