New csa2 FAQs: F002DOSMM (Part 2 of 2)

[Rubywand <rubywand@swbell.net>]

From: Rubywand

022- How can I tell which DOS 3.3 programs are safe to run
     from my GS hard disk using utilities such as
     Dos 3.3 Launcher?

     So long as a DOS 3.3 program uses only standard SAVE, etc. commands
to write to disk, it will, most likely, pose no dangers running under
Dos 3.3 Launcher from your GS hard disk. Your main concern is making
sure that the software not do special, non-standard direct writes to
disk.

     An example of destructive direct-writing is a machine language
routine which dumps game High Scores to a specially fromatted 4096-byte
block. Another example is a routine which assumes that certain tracks
are open for caching data. Such actions could mess up formatting,
over-write directories, and do other bad things to files on hard disk.

     First, you probably know enough about your own programs to say
whether or not any of them do direct writes. If all disk I/O is via the
usual DOS commands (like SAVE), then you are not doing any direct
writes.

     Non-commercial programs which have no reason to store information,
like simple arcades with no High Scores record or Game Save, are
unlikely to write anything directly to disk. One check is to
write-protect the diskette and play the game. If it does not bomb or do
a lot of clattering while attempting a disk access, it probably does not
attempt any direct writes.

     Another fairly good check is to list the program (if it's in BASIC)
under Program Writer and Search for any CALLs and & routines. If all
CALLs are to monitor routines ($F800 or higher); and, you can account
for any & commands (e.g. they play music, etc.); and, any expected Game
Saves, Pic Saves, etc. are accounted for by standard DOS 3.3 commands,
then, there are probably no direct writes.

     If, via the above checks, a program seems free of direct writes
except for CALLs to the $300 area, then, you will need to account for
these CALLS. Often, they will be for sound effects, special
screen-clears, and/or KB-input processing.

     Via the above checks, quite a few programs will seem free of direct
writes except for CALLs to code BLOADed somewhere before or after the
program. You will need to account for these CALLs.

     Any program which does CALLs to the Text Page area ($400-$700) is
very suspect as is any program which does CALLs and/or PEEKs and POKEs
to addresses which fall inside the range occupied by the program.

     Any program you cannot list and which saves information to disk is
suspect. This includes any games, word processors, and educational wares
which save scores, record position of an adventure party, maintain a
progress record, do document backups, etc..

     Any program with REMs filled with 'garbage'-- evidence of hidden
lines-- or which otherwise seems to behave oddly when listed is suspect.

     Any commercial program, especially games, educational programs, and
word processors, and any supposedly deprotected commercial program is
suspect.

     Any program which automatically reboots upon a Reset is very
suspect.

     About the only way to verify that some "suspect" program does not
do direct writes is go to the monitor and account for the functions of
machine code routines. Just noting than no JMPs or JSR's go to the usual
DOS locations does not protect against custom disk R/W routines which
can be located in all sorts of places.

Note: If code is in the Text Page or any other area which is
automatically changed when the program is halted, you will need custom
firmware to do an auto-move of these areas upon Reset. In fact, you may
need to check such areas at different times in the game, etc..

One alternative to a special auto-move is to look for and view the code
that you believe is going into the Text Page, etc. on diskette using a
utility like the Copy ][+ Sector Editor. This does not, however,
guarantee that the code is not greatly modified after being loaded by
the program.


     If any of the above conveys the impression that some wares are
trapped specifically in order to mess up disks of users who copy or in
any way modify the wares, it is because this is the case. Many other
wares do direct writes in order to speed-up game play, make a word
processor's operation more 'transparent and user-friendly, and for other
good reasons. There are, in short, lots of DOS 3.3 'icebergs' waiting to
sink your hard disk.

    So; if you did not write a DOS 3.3 program yourself or do not have
some guarantee from the program's producer or an experienced user of the
program on hard disk, then, either list the program and check the code
or forget about launching it from hard disk.

-------------------------


023- What are some good DOS 3.3 references?


DOS Books

 The DOS Manual  from Apple
 Beneath Apple DOS  by Worth & Lechner
 Apple II User's Guide  by Poole, Martin, and Cook


=============================


024- What is ProDOS?


ProDOS

     ProDOS is the official Apple ][ DOS which came after DOS 3.3. Do
not confuse "ProDOS" and "ProntoDOS". ProntoDOS is a slightly modified
DOS 3.3 which provides much faster disk I/O than standard DOS 3.3.
ProDOS is a whole new disk operating system.

----------------------------


025- What are ProDOS's major features?

     ProDOS has lots of nice features-- mainly, you can create
sub-directories, diskettes ("volumes") can be named, and ProDOS works
well on hard disks. The GS System 6 Finder can handle ProDOS files and
launch programs from ProDOS diskettes. ProDOS shares many commands with
DOS 3.3, too; so, it is not difficult for DOS 3.3 users to get started
with the newer operating system.

----------------------------

026- Which Apple II's can run which versions of ProDOS?

     All Apple II's, from the 64k Apple II+ through the IIgs, can run
versions of ProDOS up through version 1.9. Versions 2.x.x require an
Apple II equipped with a 65C02, 65C802, or 65C816 (such as an Apple
IIe-enhanced, //c, IIc+, or IIgs).

----------------------------

027- How can I create bootable ProDOS diskettes?

     Creating bootable ProDOS diskettes is a bit more bother because,
unlike DOS 3.3, ProDOS is not automatically written to protected sectors
on the diskette via an INIT command. (ProDOS does not have an INIT
command.)  Instead, ProDOS is in a file on the diskette and so is the
ProDOS 'connection' to BASIC, called BASIC.SYSTEM.

     To make new bootable ProDOS diskettes, the easiest approach is to
use Disk Muncher or some other whole-disk copier to just copy a bootable
ProDOS diskette. You can delete the files you don't want from the copy.

     Another option is to use Copy II+ (a ProDOS version) to FORMAT a
ProDOS diskette. (FORMAT writes blank tracks so that the diskette can be
used to hold files.)  Then, copy BASIC.SYSTEM and PRODOS to the new
diskette. On a IIgs, all of these operations are easily handled via the
Finder.

Note: If you want to copy ProDOS from GS/OS, copy the file P8 from the
SYSTEM/ folder and rename it to "PRODOS" on your diskette.

------------------------

028- How do I make a ProDOS disk that will start BASIC?
 
     If you want ProDOS to boot and start a BASIC program, then both
PRODOS and BASIC.SYSTEM must both be present. (BASIC.SYSTEM should be
the first .SYSTEM file on the diskette.) The "hello" program on a ProDOS
diskette is named "STARTUP". This is the program which will be run upon
booting the diskette.  (If there is no "STARTUP" program, you will end
up at the usual BASIC prompt after booting.)

------------------------

029- What is the maximum size of a ProDOS volume?

     When a diskette is formatted for ProDOS it is given a name by the
user. A ProDOS diskette is also called a "volume". A ProDOS hard disk
will, usually, be partitioned into two or more named volumes. At
present, the maximum size of a ProDOS volume is 32768 bytes.

-------------------------------


030- How do I LOAD, SAVE, etc. files under ProDOS?

     LOAD (SAVE, RENAME, etc.) work very much as in DOS 3.3.; so, you
can use Slot and Drive parms to specify the target volume. However, to
get the most from ProDOS you will usually be working with volume names
and folders. (or, "directories").

     If GAME3.PIC is a binary file in a directory named "PICS" on a
volume named "NARF", you could load it into memory starting at address
$2000 via

BLOAD /NARF/PICS/GAME3.PIC,A$2000

 or, in BASIC

100 PRINT CHR$(4)"BLOAD /NARF/PICS/GAME3.PIC,A$2000"


     So, in ProDOS, you can access a disk (or volume) by name ...

RUN /GAMES/CHINA.SEA

will find the disk (volume) named "GAMES", then, find, load, and run
CHINA.SEA.

     You can, also, refer to a disk by its location ...

CAT,S6,D1

will do a short-form catalog of the main directory of the diskette in
DRIVE 1 connected to SLOT 6.

-----------------------

031- What is a "pathname"?

      Suppose the file BARDS2.PIC is in the folder PICS on the diskette
(volume) named "NARF". Then ...

     /NARF/PICS/BARDS2.PIC is BARDS2.PIC's complete "pathname".

     /NARF/PICS/ is a "pathname prefix" for all files in the PICS
directory on the volume named "NARF".

     A leading "/" indicates a volume name (/NARF).

     The "main directory" or "root directory" is the one in which the
files PRODOS and BASIC.SYSTEM (along with any other files the user wants
there) are usually located on a ProDOS diskette. NARF's main directory
pathname prefix is just /NARF/.

-----------------------

032- What is the default volume and folder when
     ProDOS boots?

     When ProDOS boots, it will assume that LOADs, SAVEs, etc. refer to
the main directory of the volume from which it was booted. For example,
if NARF is booted and JOYSTICK.TEST is a program in NARF's main
directory, then

RUN JOYSTICK.TEST

will run the program. There is no need to enter RUN /NARF/JOYSTICK.TEST
.

------------------------


033- How can I set default volume and folder
     (directory) under ProDOS?

     The ProDOS PREFIX command lets you set the volume and folder (or
directory) .

     For example,

PREFIX /NARF

sets the current default directory to the main directory of the disk (or
volume) named "NARF".

PREFIX /NARF

also sets the default drive (that is, defaults for SLOT and DRIVE) to
that in which the volume named NARF is located. Usually, the user does
not notice or care about this feature since the location of a volume
does not, usually, change during a session. However, it _may_ change, as
when a user is swapping-in diskettes among two or three drives. If this
happens, ProDOS will look for the diskette.

     To set the default folder without changing volume, you can use the 
PREFIX command without a leading "/". For example, if the current
default volume is /NARF and NARF's main directory is the default
directory, then

PREFIX PICS

sets the current (default) directory to PICS. The default pathname
prefix would be /NARF/PICS/. Of course,

PREFIX /NARF/PICS

is also a legal command.

----------------------


034- How can I discover the name of the current
     default volume?

PREFIX

used by itself looks at the the current default drive (the drive at
default SLOT and DRIVE) and sets the default directory PREFIX to match
the name of the disk (or volume) it finds there.

     A program can discover the name of a disk (or volume) in the
current default drive as follows:

100 PRINT CHR$(4)"PREFIX": INPUT"";P$

The volume name will be saved in P$. This command is often employed
after booting to discover the volume name. Line 100 also sets the
default directory PREFIX to match the name of the disk (or volume) it
finds.

-----------------------


035- How do I create a folder?

     You can create a folder (or directory) via the CREATE command.

CREATE DHR,TDIR

would create the DHR directory in the current default directory.

______________________



From: Neil Parker

036- How do I access ProDOS routines from machine language?

     There are 26 different functions that can be performed through the
ProDOS machine-language interface (MLI), and each one takes its own
unique parameter list.  That's far more typing that I'm willing to do
tonight, but the information below should at least give a taste of
what's available. For more information, you might want to check out your
local used bookstores for old Apple ProDOS manuals, or for some of the
third-party books that used to be available (I don't even have Apple's
ProDOS manuals-- I get by just fine with _Beneath_Apple_ProDOS_ by Don
Worth and Pieter Lechner, and _Exploring_Apple_GS/OS_and_ProDOS_8_ by
Gary B. Little).

Machine-language programs call ProDOS by doing a JSR to $BF00.  This
entry point is called the machine-language interface, or MLI, and it's
responsible for carrying out almost all of the functions tha ProDOS can
perform.

To determine what function to perform, ProDOS examines the byte
immediately following the JSR instruction.  Immediately after the
command byte come two more bytes that point to the command's parameter
list.  When the call completes, it returns to the code immediately
following the parameter list pointer.  Thus, a ProDOS call looks like
this:

MLI     EQU     $BF00

        JSR     MLI
        DB      COMMAND_CODE
        DW      PARAM_LIST
        BCS     ERROR

The MLI returns with the carry flag set if an error occurred (hence the
"BCS ERROR" instruction in this example), and an error code in the
accumulator.

There are 26 command codes available:

     $40 ALLOC_INT     Set up an interrupt handler
     $41 DEALLOC_INT   Remove an interrupt handler
     $65 QUIT          Exit the current program; run prgm launcher
     $80 READ_BLOCK    Read a block from a device
     $81 WRITE_BLOCK   Write a block to a device
     $82 GET_TIME      Get the time from a clock card (if any)
     $C0 CREATE        Create a new file
     $C1 DESTROY       Delete a file
     $C2 RENAME        Rename a file
     $C3 SET_FILE_INFO Change a file's charateristics
     $C4 GET_FILE_INFO Get a file's characteristics
     $C5 ONLINE        Find the name of a disk in a drive
     $C6 SET_PREFIX    Set prefix to be added to partial pathnames
     $C7 GET_PREFIX    Get the current prefix
     $C8 OPEN          Open an existing file for I/O
     $C9 NEWLINE       Set line-terminator character for an open file
     $CA READ          Read data from an open file
     $CB WRITE         Write data to an open file
     $CC CLOSE         Close an open file
     $CD FLUSH         Flush file's block buffer to disk; don't close
     $CE SET_MARK      Set the current file position
     $CF GET_MARK      Get the current file position
     $D0 SET_EOF       Set the length of a file
     $D1 GET_EOF       Get the length of a file
     $D2 SET_BUF       Set the location of an open file's blk buffer
     $D3 GET_BUF       Get the location of an open file's blk buffer

Each call expects a different parameter list.  Like I said earlier, the
list of parameter lists is too long for me to type in tonight.  But I
can include a couple of examples...here's how to rename a file, for
example:

        JSR $BF00
        DB  $C2        ; $C2 = RENAME
        DW  REN_PARMS
        BCS ERROR

REN_PARMS DB 2         ; RENAME parm list contains 2 parms
        DW  OLD_NAME   ; 1st parm is ptr to old name
        DW  NEW_NAME   ; 2ns parm is ptr to new nme

OLD_NAME DB 8,"OLD.NAME" ; (name is count byte followed by ASCII chars)
NEW_NAME DB 8,"NEW.NAME"

And here's how to quit from a program and return to the ProDOS program
selector:

        JSR $BF00
        DB  $65        ; $65 = QUIT
        DW  QUIT_PARMS
        BRK            ; (QUIT doesn't return)

QUIT_PARMS DB 4        ; QUIT parm list contains 4 parms
        DB  0          ; All 4 parms normally null
        DW  0
        DB  0
        DW  0


_______________________



From: Rubywand

037- How can I convert DOS 3.3 wares to run under ProDOS?

     Quite a few DOS 3.3 programs will run fine under ProDOS with no
change at all. Unless you have some reason to believe a DOS 3.3 program
will not run under ProDOS, it's worthwhile to just copy it to a ProDOS
diskette and give it a try. Since DOS 3.3 programs which do direct
writes can, possibly, damage a ProDOS disk (see Question 22), be sure to
run any risky-looking tests from a booted ProDOS diskette for which you
have a backup.

     The main barriers to running DOS 3.3 programs under ProDOS are ...

1. Size: DOS 3.3 leaves more space for programs than ProDOS +
BASIC.SYSTEM. Some DOS 3.3 programs are too large for ProDOS. To use
them you will need to find ways to reduce program size.

2. Areas of memory used: ProDOS reserves parts of memory, such as Text
Page 1 ($0400-$07FF), for various pointers. Some DOS 3.3 programs
normally LOAD or BLOAD into one or more of these areas. Under unmodified
ProDOS, the result would be a BUFFERS NOT AVAILABLE error. To run these
programs you will need to unmark the reserved areas which get in the way
and/or change the location(s) of the program's troublesome LOADs and
BLOADs.

When ProDOS loads it uses most of the memory in the "language card"
areas. Some DOS 3.3 programs also use this memory. If a DOS 3.3 program
uses the "language card" it will probably have to be modified in order
to run under ProDOS. 

3. Names: DOS 3.3 file names can be longer and have more kinds of
characters than ProDOS names. If a DOS 3.3. program BLOADs, WRITEs, etc.
to any files, you will need to be sure that the file names are
compatible with ProDOS.

4. Commands and Syntax: There are, really, very few DOS 3.3 command and
syntax differences likely to cause problems under ProDOS. Still, there
are a few and you will need to check for these and make any indicated
mods.

     When checking and modifying a DOS 3.3 program for ProDOS a good
program editor is essential. You will save untold hours of work when you
invest in Beagle's tried and true "Program Writer".


_________________________



From: Jeff Blakeney

038- How can I modify ProDOS to do BLOADs in the input buffer
     and Text Page 1 areas?

     Just use a POKE 48984,192 to modify the bit map. This protects
pages $00 and $01, and unprotects pages $02-$07.

_________________________


From: Rubywand

039- How can I boot ProDOS on my Franklin computer?

     In an old Apple Clinic note, Stephen Craft mentioned the problem. 
He was running a Franklin 1000.

     His cure was to press Ctrl-Reset after the machine freezes up when
booting ProDOS. Then go to the monitor and enter two NOP (EA)
instructions at a specific address depending upon the version of ProDOS.
He then restarted ProDOS by doing a 2000G.

     It turns out that the bytes Stephen was diddling are D0 03 in the
sequence 69 0B D0 03.  The sequence is found in all versions of ProDOS
I've checked so far.


     So, to fix the booting problem, try this:

 Start Copy II+

 Select "Sector Editor"

 Swap-in the ProDOS diskette

 READ track 0, sector 0

 Search for (Hex bytes): 69 0B D0 03

 When you find the above, change D0 03 to EA EA
    and write the changed sector back to diskette.

 Check the patched ProDOS diskette by booting it.

--------------------------


040- What are some good ProDOS references?

ProDOS Books

 ProDOS Technical Reference Manual  from Apple (Addison-Wesley)
 Beneath Apple ProDOS  by Worth & Lechner
 Exploring Apple GS/OS and ProDOS 8  by Little
 ProDOS Inside and Out  by Doms and Weishaar