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 selects a menu item for processing. A selected menu item may accomplish an activity, or may call additional cards. Pressing 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 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 . 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 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 . 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 . 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 selects the volume, and pressing 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 returns you to the on-line volumes box. Pressing behaves differently if you are loading or saving files. If you are loading files, pressing 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 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 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 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 while in this card quits the program. You will then be asked to enter a title for the card. You may press 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 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 to signal you are through. You may create a card with no menu items by pressing 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 . 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 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 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 -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 . 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 , , up-arrow and down-arrow will elicit a response. Only and 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 and 27 for . 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 , 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 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 or . 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 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 key accepts the input. The 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 was pressed. If it equals 2, then was pressed. Finally, a value of 3 means open apple-H was pressed. If was pressed, go to statement 530, which processes the input. If 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 's or '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 , which means a file has been selected, or through an , which means you are aborting the operation. Check IB%(12) to see if it was and exit the card if it was. If a returns you from the subroutine, the full ProDOS pathname for the file selected will be in the variable FI$. Notice that if a 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 and the Catalog a Volume subroutine handles this. An input of "Y" or returns you from the subroutine. Check IB%(12) to see if it was 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 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 . 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 and FF was set to LOAD, the full ProDOS pathname will be in the variable FI$. If the last keypress was 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 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.