Instructions for Use of the P8 Commands
       
The files and programs on this disk which have the extension .CMD are binary
programs which install extensions to the ProDOS Basic Interpreter.  To install a
command, just BRUN it or use the "-" command.  The routine which is used to get
a buffer for the command code requires that no strings be active at the time the
command is installed.  So, if you install the commands from a STARTUP file, use
PRINT CHR$(4) not PRINT D$.  You may also have to use CLEAR to remove strings
just before the command which BRUNs the installation program.  If strings are
active, the installation program will stop and print an error message.  If the
installation program is run while a large Applesoft program is in memory and
part of the program is overwritten, the program is cleared from memory.  The
installation programs run at $2000, so any reasonable STARTUP program will not
be affected.

With each of the commands, if you want to know if the command has been installed
already, you can simply issue the command word alone from the keyboard or from
within a program and if the command is installed there will be no error.  If the
command has not been installed, BASIC will return a syntax error. If you issue a
command from within a program, you must use PRINT CHR$(4) since these are
extensions to the commands supplied by BASIC.SYSTEM and are equivalent to DOS
commands.  All of the commands can be invoked with upper case or lower case.

The TYPE command is a slightly modified version of the TYPE command by Tom
Weishaar and Mark Simonsen printed in the June 84 issue of Softalk.  Syntax is:

       TYPE pathname[,@block.number]              TYPE TEXTFILE,@3
       
The example would print the file TEXTFILE to the screen beginning with the
fourth block.  The @ parm, as with all syntax descriptions in these notes which
are enclosed in brackets, is optional.  Any file type can be typed to the
screen.  This can be instructive if used on Applesoft files with GPLE's ESC-H or
control show function active.  For laughs, try typing a directory file with the
ESC-H function on.  If you issue a PR#1, you can type files to your printer as
well.

The MORE command works like the TYPE command except that it will print twelve
lines and then wait for a keypress.  The MORE command takes the L parameter to
set the screen width in columns; once set, the screen width will stay the same
until you change it or reinstall the command.  The default screen width is 80
columns.

The COPY command copies ProDOS files.  The files may have the same or a
different name but must have different full path names. The dates of the files
will not be modified when copied; as you may have observed, the FILER changes
the dates of files when it copies them.  The one shortcoming of this COPY
command is that it will expand Sparse files. If you don't know what a Sparse
file is, you probably don't have any.  The command is much smaller, and easier
to write, because it doesn't concern itself with Sparse files.  The syntax is:
    
       COPY /source.path,/destination.path
 
       
The command may be used with full pathnames or, if the prefix has been set, you
may omit the prefix.  The slot and drive parms are ignored.

The Applesoft program called MENU.COPY will install the COPY command if
necessary and then read in a directory and allow you to mark the files to copy
from one directory to another and then ask for a destination directory.  This
program facilitates batch copying of files.  At this date, several similar but
better programs are available commercially, including COPY II+ version 6.X and
the programs supplied by Glen Bredon with Procmd and ProSel.

A companion program called EXEC.MAKER works like MENU.COPY to make up EXEC files
to drive the COPY command for file copying operations which you perform
frequently.

The program COPY.CMDS installs three commands, a version of the COPY command and
two others, ADD and PART.  ADD is used to concatenate two files.  The syntax is:
       
       ADD file1,file2
       
where file1 will be added to the end of file2 producing a new, longer file still
bearing the same name as file2.  The companion command, PART, can be used to
create a file which is a segment of a larger file.  The syntax is:
       
       PART bigfile,segment,A(block#),L(# of blocks)
       
where the file segment is created. The segment begins at the block number of the
source file given with the A parameter.  The file segment is the number of
blocks long given in the L parameter.  If you want to start with the beginning
of BIGFILE and copy the first 270 blocks to a DISKII, you might give the command
PART /HARD1/BIGFILE,/FLOPPY/SEG1,A0,L270.  If BIGFILE is less than 270 blocks
long, you would not be given an error message.  However, if you want to check to
see if all of a segment is copied, you can check the BASIC.SYSTEM parameter
VLNTH at $BE5F-BE60, which is used by PART as a counter.  If VLNTH and VLNTH+1 =
0 then the end of the source file was reached just when the number of blocks
requested had been copied, or the end of the source file was reached before the
number requested had been copied.  From BASIC you might use this line:   
     
       100  IF PEEK (48735) + PEEK (48736) = 0 THEN PRINT
       "All of the blocks requested were copied."
       
Put another way, if you write a loop to back up a large file, check VLNTH to see
if there is more of the file to copy.  If VLNTH <> 0 then there are more blocks
to copy;  if VLNTH = 0 then the last PART command copied to the end of the file
and the backup procedure is complete.

The FORMAT command does not format a disk.  It is used to format text files
which have carriage returns only to separate paragraphs into lines of any length
specified.  The syntax is:
     
       FORMAT textfile[,L66]
 

The default line length is 80 characters.

The companion command, UNFORMAT, does the opposite.  The syntax is:
       
       UNFORMAT textfile[,L35]
       
This command converts the carriage returns at the end of lines into a space but
will do so only if the carriage return occurs after the column number passed in
the L parameter.  The default column is column 65.  This parameter can be used
to preserve tabular data and short lines which aren't separated by a blank line.
 This command is useful for converting files read from bulletin boards for
editing in a word processor.  Have some patience with this command as it
processes one character at a time; when input and output are both on a ramdisk,
it works at about one block per second.

The defaults for FORMAT and UNFORMAT can be changed by changing the value at
$2003 in their installation programs.

The command FILTER copies a text file but either deletes every instance of a
character or converts it to another.  The syntax is:

       FILTER sourcefile,dest.file,A11[,B13]
       
This example will convert all character 11's to character 13's. It would convert
line feeds to carriage returns.  The value which represents the character is the
ASCII value of the character.  If the B parm is omitted, the character specified
with the A parm will be deleted.  The source file is not affected.

The MOUNT command is used to make a quick backup of a ramdisk.  It will work
only if the backup medium is equal or larger in size than the ramdisk.  For
safety, the target volume is limited to $4FF (1279) blocks.  This would prevent
backing up to a large volume on a Sider, but will allow backing up to a 3.5"
disk or from a 1 Meg ramdisk to a 1 Meg volume on a Sider.  I wrote this command
for use with a 128K ramdisk and a Disk II.  Glen Bredon's Prosel package
contains a backup utility which will allow backing up a large ramdisk or a hard
disk on multiple floppies.

This command may not work with all ramdisks.  The way it works is to copy all
blocks from the volume directory to the end of the volume, skipping blocks
marked as not used.  Most ramdisks have some blocks which are either not
implemented in the memory map or are used for code storage.  If the ramdisk
copies a block of zeroes like the IIe /RAM volume does, or returns an I/O error
when such a block is reached, then the MOUNT command should work.

To backup a ramdisk, start with a formatted ProDOS disk with a suitable name. 
The volume name must match the name you specify when you use the command.  This
is partly for safety since any data on the disk will be overwritten when the
backup is made.  The syntax is:
       
       MOUNT /RAM,/RAM.BAK
       
 
The backup disk will take on the storage size of the ramdisk and may be used as
a regular disk.  That is, you can boot from the backup disk and files may be
saved to and read from it.  The only difference is that the disk will have the
limited storage of the ramdisk.  To restore the ramdisk just reverse the order
of the command file names.  Using the same names as above:

       MOUNT /RAM.BAK,/RAM
       
DANGER !!! If you want to use this command with the /RAM volume automatically
installed by ProDOS when you boot on an expanded IIe or on a //c you must repair
a bug in ProDOS.  First unlock a copy of ProDOS version 1.1.1.  Then type the
following:
       
       BLOAD PRODOS,A$2000,TSYS
       CALL -151
       *2B4F
        0D
       *2B4F:0F
       *BSAVE PRODOS,A$2000,TSYS,L14848
       <CTRL-C> <RET>
       ]
       
       For ProDOS versions 1.0, 1.0.1, and 1.0.2 the change is *2B49:0F
       and the length of PRODOS is 15360.
       
       BLOAD PRODOS,A$2000,TSYS
       CALL -151
       *2B49
        0D
       *2B49:0F
       *BSAVE PRODOS,A$2000,TSYS,L15360
       <CTRL-C> <RET>
       ]
       
If you fail to fix the bug, the machine will crash when you try to restore the
/RAM volume.  The bug is that when you try to write to block #7 on the /RAM
volume, the code fails to protect that block and the arithmetic which maps the
blocks maps block #7 to the zero page and stack area.  When the write proceeds,
the zero page pointers are overwritten and the whole machine is scrambled.