Converter

Vincent C. O'Connor

Apple owners who send and receive files via a modem will appreciate this BASIC utility. By converting binary files into text, you can transfer non-text files without the usual hassles. And the text files created are self-converting: Simply EXEC the text file from BASIC, and the binary version is automatically written to disk. For any Apple II+, IIe, IIc, or IIGS running either DOS 3.3 or ProDOS.

One of the advantages of owning a modem is being able to send and receive programs and data files. Often, however, there's a problem transferring binary files such as shape tables, hi-res pictures, and binary programs: Many terminal programs are set up to send ASCII text files only. And although there are programs for transferring binary files, different communications software use different protocols, which means that to transfer a binary file to or from a bulletin board, the bulletin board must use the same protocol that your terminal program uses.

"Converter" converts binary files to text files. It works under DOS 3.3 and ProDOS. When run under ProDOS, Converter not only converts binary files, but Apple-Works files as well. Converter includes extensive error checking and even allows you to catalog a disk from within the program.

Getting Started

Type in and save Programs 1 through 3 using "The Automatic Proofreader" program found elsewhere in this issue. Save Program 1 using the filename CONVERT, Program 2 using the filename CONVERT1, and Program 3 using the filename CREATE.TEST. Because Program 1 runs Program 2, you must save both of these programs to the same disk.

When you've saved each program to disk, enter the command

RUN CREATE.TEST

After a few moments, the message DONE appears. The CREATE.TEST program creates a binary file called TEST on your disk. We're going to use this file to test run Converter. Also, by converting TEST into a text file and then converting it back to binary again, you'll learn how to use the Converter program.

Binary To Text

Reboot your system to clear the binary file TEST from your computer's memory. Now, load and run Converter by entering

RUN CONVERT

After a few moments, you're asked to enter a filename, or you can type in CAT for a catalog of the disk. (If you ever forget the name of a file or need to search several disks for a particular program, this catalog function is very useful.) To test-run the program, enter the filename TEST and press Return. After a moment, the screen clears and prints the message CONVERSION IN PROCESS. When the conversion is complete, the computer displays

CONVERSION COMPLETE.
RUN AGAIN (Y/N)?

Press N for no. If you catalog your disk, you'll see the file TEST.TXT. This is the converted binary file, now in standard text format.

Back To Binary

To convert the text file back into binary, simply EXEC it. As an example, let's convert the text file TEST.TXT back into binary format. Reboot your computer to remove the binary file from memory. Next, type

DELETE TEST

to delete the binary file from disk. Now, enter the command

EXEC TEST.TXT

A number of asterisks appear on the left side of the screen, followed by the message

PLACE DISK YOU WANT BINARY FILE
SAVED ON IN DRIVE 1, THEN TYPE
RUN AND PRESS <RETURN>

Enter RUN and press Return.

The disk whirs as the file is saved. If you enter CATALOG, you'll see that the binary file TEST is once again on the disk.

Restrictions

There are a few restrictions when using Converter. First, you cannot convert VAR or SYS files under ProDOS. Second, text files created by Converter tend to be two to three times larger than the original binary file. Finally, you cannot convert files that occupy the same memory locations as the BASIC Converter program. If you do, the program aborts with the message BINARY FILE HAS OVERWRITTEN PROGRAM.

How It Works

When a binary file is converted, it is translated into a text file that contains a series of BASIC and monitor commands. These commands, when executed by Applesoft's EXEC statement, reassemble the binary file in memory and then save it out to disk.

The first command the text file contains is a CALL -151 to enter the monitor. Next, the entire binary file is placed into memory using monitor commands, and the monitor is exited via a 3D0G.

Following the monitor commands is a one-line program—two lines if the file was originally an AppleWorks file (see below)—that saves the binary file back to disk. When you type RUN and press Return, the program is executed, saving the binary file and erasing the program from memory.

If the file you're converting is from AppleWorks, the program created by the EXEC file is two lines long instead of one. This is because under ProDOS, any file BSAVEd with the T parameter must first be created using the CREATE command. If the file being converted is an AppleWorks word processing file, for example, then it's created like this:

PRINT CHR$(4)"CREATE FILENAME,TAWP"

Programming Techniques

There are some useful programming techniques used in Converter that can be easily adapted for use in your own programs. The first is in line 10. By PEEKing memory location 48896, Converter can determine if you are using DOS 3.3 or ProDOS. If this location contains a decimal 76, the computer is running under ProDOS. Otherwise DOS 3.3 is assumed to be active.

Another useful routine is the decimal-to-hex conversion routines found in lines 50 and 55. The conversion routine in line 55 produces a two-character hexadecimal number between 0 and 255. Line 50 produces four-digit hexadecimal numbers ranging from 0 to 65535.

The subroutine at line 100 demonstrates an efficient way to display a catalog from BASIC, regardless of the disk operating system being used. If PR is set to 1, then ProDOS is active and the abbreviated CAT command is issued, insuring a directory that fits on the 40-column screen. If PR is set to 0, then DOS 3.3 is active and the longer CATALOG command is used. By replacing the PR = 1 in line 100 with PEEK(48896), you can place this subroutine directly into your own programs.

The subroutine beginning at line 200 shows how to access a ProDOS directory from BASIC. It begins by setting the prefix to a null path (PRINT D$ "PREFIX/"). Next, the volume name of the last drive accessed is read (PRINT D$ "PREFIX": INPUT DR$). Then, the catalog is opened and read just like a sequential text file. When you open a catalog, however, you must use the T parameter to indicate the type of file that you're accessing. In this case, the program specifies type DIR, for directory.

For instructions on entering these programs, please refer to "COMPUTE!'s Guide to Typing In Programs" elsewhere in this issue.