💾 Archived View for mirrors.apple2.org.za › archive › ground.icaen.uiowa.edu › apple8 › Pgms › FILEC… captured on 2024-08-19 at 02:33:06.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
FILECARD BUILDER DOCUMENTATION
Introduction
This utility allows you to create sets of menus which look
and function like those encountered in Appleworks, and put
them into your own Applesoft BASIC programs. It contains an
editing program which allows you to create TXT files that
contain your menus as well as a "template" program that
contains all the subroutines you need to put in your own
program to run the filecard interface. The "template"
program also serves as a sample program, with examples of
how you would accomplish various tasks using the filecard
interface.
The editor program has two parts, a loader called
FILECARD.BLDR, and the actual program, called
FILECARD.BLDR2. It also has its own filecard set, called
BLDR.FCD. All three must be in the same subdirectory for the
editor to run. Likewise, the template program has its own
filecard set, called TEMPLATE.FCD, which must be in the same
subdirectory as the template program for it to run.
The package also contains some binary programs, copyrighted
by Apple Computer, which control the user input and console
display and provide ampersand routines that facilitate
displaying the menus. These binary routines must be in the
same subdirectory as the filecard builder program for it to
work. When you write your program, a copy of these binary
utilities must also be in the same subdirectory as your
program. The names of the subroutines are:
RELEASE
RBOOT
RLOAD
CONUIR.REL
CONDAMP.REL
Be aware that if you write a program using the filecard
interface that you wish to distribute, you will have to
include these binary routines with your program. In this
case, you will have to obtain licensing from Apple Computer
to distribute them.
The system requirements for this program are an Apple IIc,
an enhanced Apple IIe with an 80 column card, or an Apple
IIgs, and a monitor with sufficient resolution to display
the 80 column characters. It runs under ProDOS. A printer is
recommended.
This program is freeware and I have obtained licensing from
Apple Computer to distribute the binary utilities with it.
Therefore, you may give copies of it to whomever you please.
If you have any need to contact me about this program, I may
be reached on GEnie at g.wright12, or on Internet at
g.wright12@genie.geis.com.
Description of Filecard Interface
The following discussion describes the filecard interface
and contains instructions for using it. You may wish to load
up the TEMPLATE program and practice some of the activities
described as you read about them here. This will make it
easier to visualize what I am talking about.
The filecard interface is a set of menus which look and
function much like the menus in Appleworks. The menus are
enclosed in boxes which are shaped like filecards, hence the
name. Each card has a tab on its upper left with its title
and the menu itself occupies the body of the card. The arrow
keys allow you to scroll through the menu items, and
pressing <RTN> selects a menu item for processing. A
selected menu item may accomplish an activity, or may call
additional cards. Pressing <ESC> allows you to leave the
card you are currently in, and return to the previous card.
Scrolling for the menu items wraps around at the top and
bottom. The highlighted menu item is the one which will be
processed when <RTN> is pressed.
The cards are hierarchical. There is one top level card
which contains the main menu for the entire program. It is
placed near the upper left corner of the screen. The main
menu card is said to be of level one. By selecting
appropriate menu item items on the main menu, the user can
invoke second level cards. These are displaced a little to
the right and down from the level 1 card, so that the user
may see the path through which the present card was reached.
The second level card will also appear to overlay and
partially cover up the main menu card. While in the second
level card, you may select menu items from it, but not from
the main menu card which called it. You may return to the
main menu by pressing <ESC>. This will cause the second
level card to be erased, and the main menu to return.
Similar statements may be made about third and fourth level
cards. A third level card may be called from a second level
card, and it will overlay and partially cover the second
level card. A fourth level card may be called from a third
level card, and will partially cover the third level card.
You may only select items from the menu on the uppermost
card of the stack (which will be the card with the highest
level). Pressing <ESC> will return you to the card directly
underneath the uppermost card.
In addition to the menus themselves, there are other
important bits of information on the screen. At the very top
left will be the title for the entire filecard set. This
will be something indicative of the purpose of the program
being run. At the very top middle will be the title of the
uppermost card, also called the current card, whose menu you
are using. At the very top right, preceded by the prompt
ESC:, is the title of the card you will back up to if you
press <ESC>. At the very bottom will be a prompt line. Any
user input will show up here.
Most of the time the prompt will instruct you to select a
menu item, and your inputs will be accepted immediately,
much as a BASIC GET statement would. However, sometimes the
user input will take the from of a line of text, followed by
<RTN>. At these times, the prompt will be followed by
several underline cursors. The number of cursors will equal
the maximum number of characters you may input. There are
some line editing features which may be used at these times
to edit your response. A help function, which can be invoked
by pressing open apple-H, lists the line editing features
for you. A prompt will appear to the right at the very
bottom when this help feature is active.
When loading or saving files, the filecard interface allows
you to choose the volume for the disk operation from a list.
The list shows the names of the on-line volumes, followed by
the slot and disk where they are. You may move through the
list with the arrow keys, much like the menu items on a
card, to select the one you want. If there are more on-line
volumes than can be displayed at once in the box, you may
see the additional volumes by continuing to press the down
arrow at the bottom of the box, and the entire list will be
scrolled to reveal more files. Likewise, when you wish to
select a file which has scrolled off the top of the list,
you may find it again by continuing to press the up arrow
while at the top of the box. The on-line volume box does not
wrap around at the top or bottom, so when you reach the last
or the first file, it will beep. As with the cards, pressing
<RTN> selects the volume, and pressing <ESC> gets you out of
the on-line volumes box and back to the cards.
When you select a volume, the filecard interface catalogs it
for you and lists the files in the box. The list will show
the file name and its file type. The ProDOS pathname will be
displayed at the top of the box. You can move through files
in the same manner as you moved through the on-line volumes.
Pressing <ESC> returns you to the on-line volumes box.
Pressing <RTN> behaves differently if you are loading or
saving files. If you are loading files, pressing <RTN>
selects a file for loading, if it is a file, or a
subdirectory for cataloging, if it is a subdirectory. If you
are saving files, you may only select subdirectories, which
will then be cataloged. When the subdirectory in which you
want to store your file is displayed in the catalog box, and
its ProDOS pathname is at the top of the box, press "Y" to
choose it as the subdirectory in which to store the file.
Pressing <ESC> will return you to the on-line volumes box,
no matter how far down into the subdirectories you are.
When you are finished with your program and want to quit,
pressing <ESC> while in the main menu card will exit to
BASIC.
Creating your own set of filecards
The program FILECARD.BLDR allows you to create your own set
of filecard menus to put in you own program. You may create
a new set, or load an existing one and edit it. The program
interfaces with the user through the filecard interface, so
you navigate through its various options using the
instructions in the previous section.
It is important to point out that you must do the actual
design of the filecard set. The program only puts the menu
sets into the proper format, adds information for creating
boxes and filecard shapes and help lists, and stores them in
a file. The sequence to follow to design the set is as
follows:
1. Design the top level card, the main menu. This involves
choosing a name for it and coming up with its menu items.
There will be a separate menu item for each activity,
whether it involves calling another card or performing a
function. Try to keep the activities general to avoid having
more menu items than you will be allowed. You can always
branch to a more specific activity in a card which is lower
on the hierarchy. Assign each menu item a unique number to
identify it. Start making an inverse tree structure to keep
track of the interconnections between the cards. The top
level card will be on top with branches coming off it to the
second level. These branches will connect to the second
level cards, those which are called directly from the top
level card.
2. Design the second level cards in the same fashion. On
each branch connecting the top level cards and a second
level card, put the number designating the menu item of the
top level card which is selected to call that second level
card. Again, connect the third level cards to the second
level cards with branches.
3. Design the third level cards in the same fashion as the
top and second level cards. Connect them to the fourth level
cards with branches.
4. Design the menu items for the fourth level cards. Since
this is the bottom level, there will be no branches coming
off the fourth level cards.
5. Once the tree structure is completed, assign a unique
number to each card. This is the order in which you will
create them. The top level card must be card 1. After that,
it doesn't really matter what order you create them in, as
long as you keep track of which card has what number.
You will also want to create a title for the filecard set.
This should be indicative of the task your program does.
While designing the filecard set, keep in mind the following
restrictions:
Maximum of 25 characters for title of filecard set
Maximum of 25 cards allowed
Maximum of 4 levels of cards
Maximum of 19 characters for title on each card
Maximum of 6 menu items on each card (I recommend that
fourth level cards be limited to 5 menu items)
Maximum of 54 characters per menu item
Now you may run the FILECARD.BLDR program to create the file
which contains your filecard set. The first time you use the
program, you may want to do a simple installation. This
involves changing the values in two variables in line 45 in
the FILECARD.BLDR program. The variable DY controls some
delay loops contained within the editor program. These delay
loops are used when you are editing one of the filecards,
and the program displays it for your examination. It is
initially set for 5000. If the delay is too long or too
short for your liking, change the value of DY. The other
variable, PS$, is the slot your printer is connected to.
Initially it is set to "1".
To run the program, just run the loader, FILECARD.BLDR. It
will install the binary utilities, load the editor's
filecard set, then chain to the main editor program. Loading
the filecards takes some time, so be patient.
The main menu presents you with several activities to choose
from, one of which is "Create a new filecard set". When you
choose this option, you will be asked for the title of the
filecard set. While entering the title, you may use the line
editing features. Enter <RTN> to accept the title. You will
then be sent to the "Edit a filecard set" menu and then to
the "Add a new card" menu to make the first card. The
program automatically numbers it as card number 1, assigns
it level 1 and sets its previous card pointer to 0, which
means pressing <ESC> while in this card quits the program.
You will then be asked to enter a title for the card. You
may press <RTN> with an empty input field if you want the
card to have no title. The card will then be shown on the
screen with its title for your examination. You will then be
prompted to enter menu items for the card. The prompt will
display a number, which identifies the menu item and which
will be shown on the card when it is used. Enter the text of
the menu item as you did the card title. If you want a menu
item to be displayed without its number, you may delete the
number in front of it using the line editing features. When
the menu item is acceptable, press <RTN> to enter it. The
card will be displayed with its new menu item. When you have
entered all the menu items you want and the prompt for the
next one appears, press <ESC> to signal you are through. You
may create a card with no menu items by pressing <ESC> when
the prompt for the first menu item appears. You will now be
returned to the "Edit a filecard set" menu.
At this point you may choose various options to add new
cards to the set, edit existing cards, or change the title
of the entire set. These options are chosen by selecting the
proper menu item on the "Edit a filecard set" card. When you
choose to add a new card, it operates the same as when
creating the first card, except that you will be asked to
specify what level the card is and what its previous card
pointer is. The card's previous card pointer is the number
of the card which called it, and to which you will return if
you press <ESC>.
Existing cards may be edited. Things you can change are the
title, the text of any menu item, the card's level and its
previous card pointer. You may also add menu items to or
delete menu items from a card. When you choose an option
which edits an existing card, you will be sent to the card
for that option, then to the "Choose card" card. You may
choose the card by typing its number, or have the program
list them for you so you can select it from the list. After
the card is chosen, it will be displayed while you are
editing it. With most of the things you can edit, there will
be already existing values, and these will be displayed as
defaults for you. After each edit, the changed card will be
shown for you to review.
When you choose to add menu items to a card, you may place
the new item anywhere in the list of items. The program will
ask you which item the new item follows. If the new item is
to be the first item, tell the program the item follows item
0.
At various points in the editing process, you will be asked
to supply one character answers to questions, which will be
acted upon immediately when you enter them. At these times,
you may enter either the upper case or the lower case of the
letters allowed. If you enter any character other than the
ones asked for, nothing happens except a BEEP. The only
exception is that, if appropriate, you may be allowed to
<ESC> from the operation.
If you are editing a filecard while it is being displayed
and press open apple-H to get line-edit help, then press
<RTN> to leave the help box, the program will erase the
prompt area in the process of restoring the card display. It
will reprint the prompt, but, depending on where the cursor
is when you pressed open apple-H, not all of your input
string will be reprinted. The string is still there, and you
can restore it by moving the cursor left with the left arrow
key. Alternately, you could hit <CTRL>-Z to reprint the
default input string. However, this will reverse any changes
you had made to the default string.
Once you have created the filecard set, you may save it by
choosing that option from the main menu. After going through
the on-line volumes box and the catalog of a volume box, you
will be prompted for a name for the file. The name does NOT
have to be the same as the title of the filecard set. The
program automatically appends ".FCD" to the end of the file
name, so you may only enter an 11 character name.
A pre-existing card set may loaded up and edited. Select the
"Load a filecard set" option from the main menu and choose
the file from the catalog of the desired volume. The
filecard sets all have ".FCD" appended to their file names,
so the program will not allow you to load anything which is
not a filecard set. When you have loaded a pre-existing set,
edited it and chosen to save it, the program presents you
with a default file name which is the same as the original
file name.
While you are doing load or save operations on the
filecards, do not take the volume with the FILECARD.BLDR
routines out of the disk drives. This is because the program
always resets the default prefix back to the original prefix
when it finishes the file operations. If the volume has been
removed, the program will not be able to find the it and
will bomb. If you only have one disc drive, you will want to
copy the filecard set you want to work on onto the disc
containing the FILECARD.BLDR routines.
A final feature of the program is the filecard summary. This
is chosen from the main menu. The filecard summary lists all
the cards by their numbers. For each one its title is
displayed, all the menu items are listed, and its level and
previous card pointer are displayed. The summary may be
output to the screen, in which case the cards are displayed
one at a time. You move to the next card in the set by
pressing <RTN>. You may also send it to the printer, in
which case the cards are all printed out at once.
Putting the filecards into your program
The template program is the vehicle for putting the
filecards into your own program. In lines 0 through 9 it
contains the statements needed to initialize the filecard
system. This includes loading the binary utilities that run
the console display and user input, and loading the
filecards into memory. Lines 9000 through 9999 contain the
BASIC subroutines which run the filecards. With two
exceptions, which I will explain, you won't have to do any
modifications to these lines of code to create your own
program. Lines 10 through 810 contain sample code showing
how various common tasks may be accomplished using the
filecards. Your own program would replace these lines,
although you are not limited to using only line numbers 10
through 810. Any numbers which are not in the ranges 0 to 9,
or 9000 to 9999 are okay.
The general procedure to creating your own program is this:
1. Design and create a set of filecards using
FILECARD.BLDR
2. Copy the TEMPLATE program to a file with a new file
name
3. In line 2 replace TEMPLATE.FCD with the name of your
own filecard set
4. Delete lines 10 through 810 and replace with code for
your own cards
5. Note the beginning line numbers for the code
corresponding to each card by the card's number. These line
numbers will replace the ones in the ON CC GOTO ...
statement in line 9153. When you leave a card and return to
its previous card, this statement directs you to the right
line number for the previous card. You don't need to include
a line number for every card in the set, but the minimum
number is the highest number which corresponds to a card
which is a previous card for another card.
Some general comments may be made about the code for the
cards. First, it is modular. There is one module per card,
and the code for that card is all in one spot in the
program. You will also probably be able to debug each card's
module as a separate unit.
Secondly, the subroutines which run the filecards frequently
require that you set the value of a variable to a desired
value before executing a GOSUB to that subroutine. There are
also times when the subroutine will set the value of a
variable which you will need to use in the module after
returning from the subroutine. Examples of these are
included in the sample modules of the TEMPLATE program, and
I will describe them when I discuss the samples later.
Lastly, there is one place where you will have to execute
some of the ampersand command which invoke the binary
utilities which control the console display and user input.
The number of such commands you will have to use are small,
and largely you will be copying statements exactly as they
are in the sample modules.
While writing modules for the cards, you must keep in mind
that there are two kinds of cards: those whose primary
function is to call other cards, and those which perform an
activity. The modules for the two types are different, and I
will describe them separately. These discussions will refer
to the modules in the TEMPLATE program, so it is helpful to
have a listing of the program handy.
Cards that call other cards
Examples of this type of card are the Main Menu card (lines
10 through 50), the File Activities card (lines 60 through
100) and the Misc. Activities card (lines 170 through 210).
The modules for these cards begin by setting CC to the
number corresponding to the card this module codes for. They
then GOSUB to the subroutine which prints the card shape and
the menu (at 9450). After this they GOSUB to the subroutine
which prints the prompt at the bottom (at 9550).
The next statement, GOSUB 9050, calls a subroutine that
clears out the variable containing the last character
pressed and changes the memory locations which record the
status of the console display utilities. All modules, with
the exception of the module for the first card, must have
these statements.
Next, the subroutine that gets a keypress is called, which
is at 9600. While in the subroutine, only <RTN>, <ESC>,
up-arrow and down-arrow will elicit a response. Only <RTN>
and <ESC> will return you to the card module. When you
return from the subroutine, the ASCII value of the last
keypress will be contained in the variable IB%(12), 13 for
<RTN> and 27 for <ESC>. NOTE THAT IB%(12) IS AN INTEGER!
Check this variable to determine what the last character
was. You will branch to different parts of the module
depending on its value.
If the last character was an <ESC>, you will go to the
Back-Up-a-Level subroutine. When executed from the first
card, you will exit the program. This is accomplished by
GOTO 9200. When executed from any of the other cards, you
will go to the subroutine that erases the card you are in
and returns you to the previous card. This is accomplished
by GOTO 9150.
If <RTN> was pressed, you will go to an ON CI GOTO ...
statement. The Get Keypress subroutine returns the number of
the menu item that was selected in the variable CI. The line
numbers in the ON CI GOTO ... statement correspond to the
start of the module which codes for the card which is chosen
by the selected menu item.
The statements which check for the last keypress and branch
accordingly are followed by the GOSUB which sets the last
character variable to 0, and returns you to the statement
which calls the Get Keypress routine. This is largely
assurance against somehow returning from the subroutine with
a keypress other than <RTN> or <ESC>.
You are also allowed to put statements that include
immediate activities in the modules for a card that chooses
other cards. An example of this is in the Main Menu card
module. If you choose menu item 4 (EXIT), line 50 sends you
to 9200, which exits the program. Another example is in the
Misc. Activities card module. If you choose menu item 1
(BEEP) statement 210 sends you to line 220. This contains a
GOTO 9650, which is the subroutine that sounds the beep.
Cards that perform an activity
These cards start out by setting CC to the number
corresponding to the card, and going to the Print Card
subroutine, much as the cards that call other cards do.
However, after that they differ in that the following
statements code for the activity which is to be
accomplished. I will describe the specific examples from the
TEMPLATE program to show how some common activities may be
accomplished. These cards all end with the statement GOTO
9150, which returns you to the previous card.
1. Enter Your Name card (lines 450-560)
This shows how to get a line input from a user. First you
must set the width of the input field, which is done by
putting the appropriate value into the variable I1. The
field width is the maximum number of characters the user
will be allowed for this input. In the current filecard
system, it isn't practical to set the field width more than
70, or you will begin to overwrite parts of the display. If
you have a prompt, the field width should be decreased
accordingly. Next, you will set the default input string by
putting it into the variable I$. If you don't want to have a
default, be sure to set I$ to null to clear out any prior
value it may have had.
Next, set value of the variable S$, which contains the
prompt message. Even if you don't want to have a prompt
message, set S$ to null to clear out any prior value it may
have had. Then GOSUB 9551 to print the prompt. This call is
similar to the GOSUB 9550 encountered earlier, except in
this case you have set the prompt message, so you can skip
over the portion of the subroutine that sets the prompt
message.
Next you will call a subroutine which prepares the user
input utility to accept a line input, subroutine 9300. In
this mode, inputs will operate much like the BASIC INPUT
command in that characters the user supplies are not
accepted and acted upon until a <RTN> is pressed. This
subroutine also prints a reminder in the lower right corner
that you may get a listing of line editing commands by
pressing open apple-H.
Line 500 calls a subroutine that contains the actual command
to accept input, subroutine 9100. Once it is called, the
input field will appear in the prompt area, consisting of
underline cursors. There will be as many underline cursor
characters as the field width has been set to. If you have
set a default string, it will be displayed, and will take up
part of the beginning of the field. As each character is
entered, the underline cursor at that point will be replaced
with the character.
The input can be terminated by three keys, and you will then
be returned from the subroutine. The <RTN> key accepts the
input. The <ESC> key aborts the input operation and exits
the card. The open apple-H combination interrupts the input
to display help on the line editing features. Whenever an
input has been terminated, you will have to check which key
has been pressed and branch to the appropriate statement.
This can be done by checking one of the values in the
integer array holding the status information for the console
display utilities. In this case, you will want to check the
value of IB%(10). Then use the value of IB%(10) in an ON
IB%(10) GOTO ... statement to branch to the appropriate
statement. IB%(10) contains an integer designating which
keypress terminated the input. If it equals 1, then <RTN>
was pressed. If it equals 2, then <ESC> was pressed.
Finally, a value of 3 means open apple-H was pressed. If
<RTN> was pressed, go to statement 530, which processes the
input. If <ESC> was pressed, go to statement 550, which
exits you from the card. If open apple-H was pressed, branch
to 520, which sends you to subroutine 9400. This is the
subroutine which prints the line edit help. After returning
from the subroutine, you will want to continue the input
operation, so GOTO 500.
Exiting the card is slightly more complex that exiting cards
that have no line input functions. First you must reset the
user input utility back to the "GET" mode, so that the menu
items may be selected as before. This is accomplished by
GOSUB 9350. Then set the default string variable, I$, to
null to clear any <RTN>'s or <ESC>'s from the last character
variable. Finally, GOTO 9150.
2. Display a Message Box card (lines 600-650)
The Display a Message Box card overlays a portion of the
screen with a box with a message in it. These can be useful
for alerting a user to an error condition and what should be
done to remedy it. You will be limited to a message of one
or two lines, each of which has 50 or less characters. First
you must set the variable I to the number of lines in your
message. The first line of the message is then put into the
variable M1$, as shown in line 620. If you want to have two
lines in the message, put the second line of the message
into the variable M2$. Clear out the last character
variable, as in line 630. Then call the Display a Message
Box with the statement GOSUB 9850. Upon returning from the
subroutine, exit the card as normal.
3. Load a File card (lines 230-300)
This function requires that you set the SAVE/LOAD flag, FF.
For file load operations, set it to zero. Then, line 245
stores the "home" prefix in a temporary variable. This is
necessary because the sub you are about to call changes the
default prefix one or more times, and by the time control is
returned to your module you won't know what it is. Include
the statement POKE 1403,78 to put the cursor at the end of
the line before you execute the BASIC INPUT statement that
retrieves the prefix. Since the BASIC INPUT statement erases
everything from the cursor to the end of the line, this
statement will prevent it from erasing part of your filecard
display.
Next, GOSUB 9700, which is the subroutine that displays the
box with the on-line volumes. Once you have chosen a volume,
the subroutine will automatically send you to the Catalog a
Volume subroutine. Return from these two subroutines in a
load operation can only occur through a <RTN>, which means a
file has been selected, or through an <ESC>, which means you
are aborting the operation. Check IB%(12) to see if it was
<ESC> and exit the card if it was. If a <RTN> returns you
from the subroutine, the full ProDOS pathname for the file
selected will be in the variable FI$.
Notice that if a <RTN> returned you from the subroutine, you
are directed to statement 265, rather than being allowed to
drop into statement 260. This arrangement allows you to put
in an error trapping routine, which occurs at line 270, to
see if the wrong type of file has been selected for the
following operation. An example of such an error trap is
line 15 in the FILECARD.BLDR2 program, which checks to see
if the filename has ".FCD" appended to the filename to
ensure it is really a set of filecards. If there is an
error, the user may be alerted with a message box. Then go
back up to statement 260. This sends you back to the Catalog
a Volume box, and you can choose another file. If there is
no error, drop down into statement 280 to actually load the
file. Finally, line 295 restores the default prefix to its
"home" value.
The statement in line 265 requires a little explanation. It
sends you to the subroutine, at line 9350, which restores
the GET mode for input. Execute this statement even though
you never really left the GET mode during the load
operation. The cursor position may get reset as the various
prompts are used for the load operation. The subroutine
resets the cursor position to the beginning of the prompt
line at the bottom. Then, when the program exits the card
and prints the standard prompt message, the cursor will be
placed directly after the prompt. If you neglect to call the
subroutine and reset the cursor position, the cursor will
remain in the same position as it occupied after the last
prompt in the Catalog A Volume subroutine, and this may not
be in the right place.
4. Save a File card (lines 310-440)
To perform a save file operation, you must first set the
SAVE/LOAD flag, FF, to one. Save the "home" prefix in a
temporary variable. Then call the On-Line Volumes Box
subroutine with the statement GOSUB 9700. After choosing the
volume you will be sent to the Catalog a Volume Box to allow
you to choose a subdirectory. Subdirectories are selected by
pressing <RTN> and the Catalog a Volume subroutine handles
this. An input of "Y" or <ESC> returns you from the
subroutine. Check IB%(12) to see if it was <ESC> and exit
the card if it was. If you were returned from the subroutine
by an input of "Y", the ProDOS prefix will be contained in
the variable PX$.
Once you have been returned from the subroutine with the
ProDOS prefix, you must specify a filename to store the file
under. This will be accomplished by setting up for a line
input, as done in the Enter Your Name module. Set the field
width, variable I1, to 15 characters, which is the maximum
length for a ProDOS filename. If you will be appending
anything onto the end of the filename, reduce the field
width accordingly. If there is a default filename, put this
into I$. Put your prompt message into S$ as in line 350 and
call the Print Prompt sub with GOSUB 9551. Ask for the
filename with the statement GOSUB 9100. After the input is
terminated, check for which terminator is active, and branch
accordingly. If the terminator was a <RTN> the filename will
be contained in the variable I$. The full ProDOS pathname
can be obtained by concatenating PX$ and I$ with
appropriately placed /'s. Then you can perform the desired
save operation on the file.
When the save operation is finished, restore the default
prefix to the "home" prefix and exit the card in the same
fashion as you exit the Enter Your Name card. Call the
subroutine which restores the "GET" mode of input, clear the
input variable, and go to the Back Up a Level subroutine.
5. Answer a YES/NO question (lines 700-810)
This module shows how you would set an input for a user to
press a key to choose one from a very small number of
available options, in this case, two. The keypress will be
acted upon immediately, without waiting for the user to
press <RTN>.
The card is started by setting the current card number in CC
and calling the subroutine that prints the card. Then, in
line 720, you make a call to the subroutine that sets the
"GET" mode of input. In this case, you make a call to an
alternate entry point for the subroutine, at line 9351.
Again, call this subroutine even if you are already in the
"GET" mode. Not only does this reset the cursor position so
that it ends up right after the prompt, but the alternate
entry point has statements that ensure the cursor blink rate
remains the same for the YES/NO questions as it was for the
standard GET mode.
Next, put your prompt into S$ and call the subroutine that
prints it. Line 740 is where you actually ask for the input.
Call the subroutine that resets the last character to zero,
sub 9050. Then call the subroutine that invokes the INPUT
command, sub 9100. Note this is the same subroutine you
called in the "Line Input" mode to ask for input. The
difference is that, in the "GET" mode, the subroutine checks
if a key has been pressed and returns regardless of whether
a key has been pressed or not. You will need to check
IB%(12) to see if a key has been pressed. It will be zero if
no key has been pressed. In this case, loop back to line 740
to go check for a keypress again.
If a key has been pressed, check which key was pressed. The
sample module explicitly checks for each of the allowed
input keys. This prevents the user from accidentally
choosing the wrong option by hitting the wrong key. This
module also allows the user to press the upper or the lower
case of the allowed keys. Line 750 checks for "Y" or "y"
input by checking if IB%(12) equals the ASCII value for
either of these letters. If it is, you are sent to line 780.
Line 760 checks for "N" or "n" input, and sends you to 790
if it is. If you pressed something other than "Y", "y", "N"
or "n" you will drop into line 770. This calls the BEEP sub
to alert you that you made an illegal choice, and returns
you to line 740 to try again.
Lines 780 and 790 set messages to be shown on the prompt
line in response to your input. Line 800 calls the print
prompt sub and delays briefly to allow you to see it.
Line 810 exits the card. Before exiting, you must first call
the subroutine that sets the "GET" mode. This will reset the
cursor position so that when you next display the prompt for
the arrow inputs that choose menu items, the cursor will be
in the right spot. This time you call the standard entry
point for the subroutine, so the cursor blink rate will be
set for the standard prompt line. Then exit the card by
calling subroutine 9150.
6. Fourth Level Card (lines 570-590, 660-690)
This card doesn't really do anything. None of the menu items
have any functions attached to them, and you are not allowed
to select any of the menu items. I included it to show you
why I recommend that level four cards have five or less menu
items. When you run the TEMPLATE program and choose to
display this card, the prompt line overwrites the sixth menu
item. Since it can only be seen very briefly, it is not of
much use.
Launch an Application
There are a number of ways to launch an application from the
filecard system. Since it is an involved topic, I will cover
it in its own section, rather as one of the cards which
perform a task.
The example in the TEMPLATE program (lines 110-160) is
probably going to be the most common way of launching an
application. This method will be used if you can avoid
changing the values in the variables that run the filecards.
Later in this document, I will be listing these variables,
so that you can write your application using different ones.
You will also have to avoid writing over the memory area
above HIMEM which contains the binary utilities that run the
console display and user input. If these conditions can be
satisfied, you will first execute the ampersand command
&EXITINPUT, which is shown in line 120. This stops the
utilities and restores the standard APPLESOFT I/O. Branch to
the first line number of your application. Your application
should designate some keystroke which will signal it that
you want to return to the filecards. At this point, you
would branch to a statement such as line 150, which contains
the statements CALL A2%:&STCDADR(A1%). These restart the
console display and user input utilities and reconnect the
ampersand commands. Then you would go back to statement 7 to
redisplay the filecards.
If your application is well suited to being menu driven, it
may be possible for you to avoid the process in the previous
paragraph. Just add filecards to the existing set which
reflect the menus of you application. Have them called from
appropriate places in the existing cards. Write the modules
that connect the new cards to each other and that perform
the activities you need done. In this scenario, you never
need to execute &EXITINPUT, because you never need to leave
the filecard system.
In the event that you can't avoid changing the values of the
variables that run the filecards, there are a couple of
options. If the number of variables to be disturbed is
small, you may be able to store the values in some dummy
variables before exiting the binary utilities. These values
could be restored to their original variables just before
going to statement 7 when you return from the application.
If there are large numbers of variables which will be
changed, you may want to use the STORE command to save them
before exiting the utilities. A good place to do this would
be the /RAM disk, since the filecard system doesn't use
/RAM, so there is room there. These could be recalled using
RESTORE just before going to statement 7.
In the event that you cannot avoid writing over the memory
above HIMEM where the utilities are stored, you will have to
reload the utilities from disk. You do this by going back to
statement 0. In this instance, you don't need to STORE and
RESTORE the variables from disk, since the program will
recreate them.
If your application is very large or uses a very large
number of variables, you may begin to run out of memory. In
this case, you will probably have to put the filecard system
in one program and your application in another program. When
the appropriate menu item is chosen from the file cards, the
module can RUN the application program. Similarly, the
proper keystroke within the application can cause the
application to RUN the filecard program. Obviously you would
want to STORE the variables from the application, so that
you don't lose all your work when you call up the filecards.
These could be RESTORE'ed after you return to the
application from the filecards. Again, putting things into
/RAM will cut down on disk access time.
Reference items you need to know
There are a few additional things you will need to know in
order to write modules for the filecards and to write
applications which are compatible with the filecards.
1. If your program is stopped because of an error while you
are writing and debugging it, be sure to execute the command
&EXITINPUT before trying to run the program again. This
disconnects the console display and user input utilities. If
they are not disconnected, the program will crash next time
you try to run it.
2. Here is a list of the variables which the program uses.
Some of the variables may not be changed. Other variables
are temporary variables, which you may also use as temporary
variables. Be aware that any temporary variables may have
their values changed as soon as you go to one of the
subroutines.
Variables which you must not change:
A1%, A2%, AC$(), AM$(), AR, BX$(), CC, CI, CT$(), D$, FC$(),
FT$(), H$(), HB$(), HP$(), IB%(), L$, LV, LX, LY, MI$(),
TL$, TV$, UX, UY, VP()
Temporary variables:
A$, C, CD$, CF, CH, CV, DF, FF, FI$, FI$(), G$, GT$, I, I$,
I1, J, K, L, L1$, L2, M1$, M2$, MF, MM, NC, NF, NM, NO, OV$,
P$, PT$, PV, PX$, S$, TC$, TR$, W$
3. Here is a list of the subroutines which you will need to
call, and the variables through which you either send them
information or receive information from them.
9050: Reset the last character variable to 0.
9100: Executes the "INPUT" command. It returns the status if
the console display utilities in the integer IB%(). You may
need to use the value in IB%(12) (the last character
pressed) or the value in IB%(10) (the type of terminator
that stopped the input operation).
9150: Exit current card and go back to previous card
9200: Exit program
9300: Set user input utility to line input mode. Field width
is sent to subroutine in variable I1.
9350: Set user input utility to "GET" mode
9351: Alternate entry point for the subroutine which sets
the input utility to the GET mode. This entry point is used
when setting up a YES/NO question.
9400: Print line edit help
9450: Print current filecard and menu. Current card number
is sent to subroutine in variable CC.
9550: Print prompt message at bottom. Program supplies text
of prompt message.
9551: Print prompt message at bottom. User supplies text of
prompt in variable S$.
9600: Get keypress during selection of a menu item.
Subroutine returns ASCII value of last keypress in variable
IB%(12).
9650: Sound the BEEP
9700: Go to the On-Line Volumes Box subroutine. The user
specifies if the desired operation is LOAD or SAVE by
setting FF to zero or one. The ASCII value of the last
keypress will be returned in the variable IB%(12). If the
last keypress was <RTN> and FF was set to LOAD, the full
ProDOS pathname will be in the variable FI$. If the last
keypress was <RTN> and FF was set to SAVE, the ProDOS prefix
will be returned in the variable PX$.
9750: Go to the Catalog a Volume Box subroutine. The ASCII
value of the last keypress will be returned in the variable
IB%(12). If the last keypress was <RTN> the full ProDOS
pathname will be returned in the variable FI$.
9850: Go to the Display a Message Box subroutine. The user
sends the number of lines in the variable I. The first line
of the message text is sent in the variable M1$. The second
line, if any, is sent in the variable M2$
4. Here are the ampersand commands that you will be using in
the program. Type them exactly as shown. Their uses are
explained in the section on cards which perform an activity.
&EXITINPUT
&STCDADR(A1%)
WARRANTY DISCLAIMER
GERALDINE WRIGHT'S LICENSOR(S) MAKES NO WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE, REGARDING THE SOFTWARE. GERALDINE WRIGHT'S
LICENSOR(S) DOES NOT WARRANT, GUARANTEE OR MAKE ANY
REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE
OF THE SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
RELIABILITY, CURRENTNESS OR OTHERWISE. THE ENTIRE RISK AS TO
THE RESULTS AND PERFORMANCE OF THE SOFTWARE IS ASSUMED BY
YOU. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY
SOME JURISDICTIONS. THE ABOVE EXCLUSIONS MAY NOT APPLY TO
YOU.
DISCLAIMER OF LIABILITY LANGUAGE
IN NO EVENT WILL GERALDINE WRIGHT'S LICENSOR(S), AND THEIR
DIRECTORS, OFFICERS, EMPLOYEES OR AGENTS (COLLECTIVELY
GERALDINE WRIGHT'S LICENSOR) BE LIABLE TO YOU FOR ANY
CONSEQUENTIAL, INCIDENTAL OR INDIRECT DAMAGES (INCLUDING
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION,
LOSS OF BUSINESS INFORMATION, AND THE LIKE) ARISING OUT OF
THE USE OR INABILITY TO USE THE SOFTWARE EVEN IF GERALDINE
WRIGHT'S LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES. BECAUSE SOME JURISDICTIONS DO NOT ALLOW THE
EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR
INCIDENTAL DAMAGES, THE ABOVE LIMITATIONS MAY NOT APPLY TO
YOU.
Geraldine Wright's Licensor's liability to you for actual
damages from any cause whatsoever, and regardless of the
form of the action (whether in contract, tort (including
negligence), product liability or otherwise), will be
limited to $50.