Play and Learn 2

home *** CD-ROM | disk | FTP | other *** search

/ Play and Learn 2 / 19941.ZIP / 19941 / EDUCMISC / STDYAID2 / Q&ASA.DOC < prev next >

Wrap

Text File | 1994-02-04 | 64.7 KB | 1,811 lines

Q & A Study Aid (Q&ASA) Version 2.1 July 31, 1988 Hal Endresen Quid Pro Quo Software 1703 Marlbrook Lane Lansdale, PA 19446 Q&A Study Aid User's Guide Revision Information -------------------- Version 1.0 January 7, 1988 Initial release. Version 2.0 March 22, 1988 Major enhancements to allow Q&ASA to be used in a formal classroom environment. Among the changes are the following: * Optional logging of scoring information to a disk file. * Compiled database eliminates run-time interpreter errors and permits the database to be encrypted. * Display of the database name as the window title. * Faster response when loading questions. * Greatly improved help system allows selection and viewing of any help category at any time. * Optional locking of selected mode and lockout of certain commands. * Ability to assign a weight to each question and have this weight determine the number of points awarded for a correct answer to a question. * Ability to specify a time limit to answer all questions. * Elimination of all index files. Version 2.1 July 31, 1988 Minor enhancements to help system. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 1 Q&A Study Aid User's Guide Introduction ------------ Q&ASA is a general-purpose program designed to present questions from a database. The user is then prompted for an answer and graded accordingly. Q&ASA provides two methods of reading the questions from the database: sequential and random. The program starts up in sequential mode. A menu-driven command interface is provided with pull-down menus. Filenames are selected from a directory by pointing. It is never necessary to type in a filename. Q&ASA supports an elaborate context-sensitive help system accessible via the F1 key. Help is provided by a single support file, Q&ASA.HLP. This file may be located in the current directory or in any directory specified in the PATH environment variable. Q&ASA may therefore be placed in the \bin (or equivalent) directory and accessed from any other directory, provided that PATH includes \bin. If you place Q&ASA in a directory that is not in the PATH string such that it is unable to locate its help file, Q&ASA will, as a last resort, pop up a window and ask you to enter the name of directory containing the help file. Q&ASA now uses a compiled database. The database compiler is included with the package to allow you to create and compile your own databases. The database compiler is called Q&AC.EXE. Both Q&ASA.EXE and Q&AC.EXE are written in the C language. This package contains the following files: Q&ASA.EXE Q&ASA main program Q&AC.EXE Q&ASA database compiler Q&ASA.HLP help file Q&ASA.DOC documentation file REGISTER program registration form SAMPLE.Q&A sample database (compiled) SAMPLE.DEF database definition file for SAMPLE.Q&A The Q&A Study Aid package is SHAREWARE and is copyrighted by the author. If Q&ASA meets your needs, you are expected to register and pay for its use. The SHAREWARE concept allows users to obtain high quality software at bargain prices, and rewards authors for their efforts. Please support this distribution concept by registering your copy. You will find a registration form at the back of this manual. You have unlimited rights to copy and distribute the program, provided you distribute it as the complete archive STDYAID2.ARC. Comments, bug reports, or other information that may help me improve this program are welcome. Q&ASA is offered as is. There is no guarantee that it will work on your particular system; however, it has been tested with CGA, MDA and EGA monitors on both PCs and ATs. Text mode is used; no graphics card is Copyright (C) 1987, 1988 Quid Pro Quo Software Page 2 Q&A Study Aid User's Guide needed. Q&ASA will NOT use an EMM if one is present. A minimum of 128K of available RAM is needed by the program; it will tell you if you do not have sufficient memory to execute it. All I/O is performed through system calls, with the exception of the screen, which is controlled by direct writes to the regen buffer. Under Microsoft (c) Windows, you must give Q&ASA control of the screen. A command has been provided to control the screen updating method to eliminate any 'snow'. Q&ASA will start in the FAST screen mode, meaning that it will not wait for any synchronizing signals before writing to the screen. This is the best mode for use with EGA systems. Q&ASA assumes that your screen is set to 80x25 text mode (color or monochrome). If not, it will NOT reset the mode. If your screen is in any of the graphics modes when Q&ASA is invoked, you will see garbage. Exit Q&ASA using the /FX command and reset the mode manually. User Interface -------------- Commands are entered into Q&ASA via a pull-down two-level menu system. The uppermost screen region is the menu system. Each word group on the menu line is the title block of a pull-down menu. Whenever one of the titles is selected, the menu expands to display any options available under it. Under most conditions, Q&ASA will be prompting for an answer to a question. Some means must therefore be provided to break out and into the menu system so that an option can be selected or a command given. There are two ways of doing this: via an ALT key sequence or by pressing the menu escape character, the forward slash ('/'). If an ALT sequence is used, it is only necessary to press one or two ALT keys to select any command option. A top-level selector is specified by ALT-shifting the highlighted letter. For example, the "Mode / Sequential" command is executed with ALT-M/ALT-S. If you use the '/' menu escape character, the word MENU will first appear at the right of the menu line to indicate that you are in the menu system. At this point, any combination of highlighted and underscored letters and cursor keys can be used to select a command option. Note that F1 will always get help no matter where you may be, in or out of the menu system. Once the desired option has been selected, RETURN executes it. Note that neither the slash nor the RETURN are necessary when using ALT-key sequences. Q&ASA's commands are listed on the following page. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 3 Q&A Study Aid User's Guide Q&ASA Command List ------------------ /FS select database /FD specify directory containing database file(s) /FX exit to DOS /MS set mode to sequential /MA set mode to pseudorandom /MC clear score /N enter name /SF select FAST screen updates (no sync delay) /SM select MEDIUM screen updates (horizontal sync) /SS select SLOW screen updates (vertical sync) /FD - Specify Database Directory -------------------------------- If your Q&ASA database file or files are located in a directory other than the directory Q&ASA is invoked from, then you must tell Q&ASA which directory to use with this command. When selected, a data entry window will pop up and prompt for the directory name. DO NOT enter a filename - just the name of the directory. You may prefix the directory name with a drive letter and colon if you wish. The directory will be verified as such, and you will receive an error if the directory does not exist. The directory you specify need not be on the same disk drive. However, if you give the name of a directory on a floppy disk, you must have the floppy in the drive with the door closed or you will get an error. /FS - Select Database File -------------------------- This option is used to specify the name of the database file you want Q&ASA to use. Once selected, a list of all of the compiled database files in the directory you specified with the /FD command will appear in a selection window along with a selector bar. Q&ASA will NOT display any files other than compiled database files. To select a compiled database file, move the selection bar to it using the cursor keys, page up and down, or home and end. Each of these permits traveling up and down the scrollable list in larger increments. Alternatively, you may also press a letter key that corresponds to the first character of the database filename; Q&ASA will find the first file beginning with that letter. Successive depressions of the same key will step to each filename that begins with that letter. The search stops at the last file that begins with that letter. The search always proceeds down the list; to restart the search, press HOME to move the selector back to the first file in the list. Once you have pointed to the file you desire, press RETURN. The compiled database file index will be loaded. If the optional score logging has been enabled in the database, Q&ASA will request that you Copyright (C) 1987, 1988 Quid Pro Quo Software Page 4 Q&A Study Aid User's Guide enter your name for the score file. The first question will then appear on the screen, along with the number of questions in the database in the scoring window. The name of the database will also be shown in the center of the top border of the question window if it has been specified in the database. If not, then the window title will default to "Question". Each time you load a database file with score file logging enabled, Q&ASA will request your name, even if you have already entered it. This is to allow other users to reload the same database without using the same name for all users. If score file logging is not enabled, Q&ASA doesn't force you to enter your name. You may do this anyway using the /N (Name) command, and Q&ASA will display it when it displays your final score. If the database you load has a time limit associated with it, the time remaining will be displayed in the status window under the heading 'Time Left', and the clock will start. The time is counted down to zero, and always shows the time you have remaining before Q&ASA stops you and calculates your final score. If the database does not specify a time limit, the 'Time Left' will be displayed as 'No Limit'. If you allow the time to count down to zero, it will change to 'Time Out'. To permit Q&ASA to utilize relatively large databases (>3000 questions and their answers), Q&ASA loads an index into memory rather than the database file itself. The database index is created by Q&AC and is a header in the database file itself. The database file (.Q&A) should never be changed directly, as it is encrypted to prevent users from typing the file to the screen and thereby viewing the answers. If you wish to create a new database or alter an existing one, you must edit the database definition file (.DEF) and recompile it using Q&AC. Q&AC will create a (.Q&A) file from your (.DEF) file. Q&AC will not permit you to use the .Q&A extension on a definition file, so you cannot accidentally overwrite a definition file. You must create the database definition file and compile it before Q&ASA can be used. Instructions for doing this are in a later section of this document. Note that this package contains a compiled database that you may use to test and evaluate Q&ASA. This file is called SAMPLE.Q&A. The database definition file it was created from is also included, and is called SAMPLE.DEF. /FX - Exit to DOS ----------------- Use this command to quit a Q&ASA session and return to the operating system command level. If you have loaded a database but have not answered all questions, the score file will be updated with your current score and a notation that you quit Q&ASA. You cannot exit Q&ASA, clear the database, or reload the current or new database without updating your score file. This prevents extending time limits and/or starting a quiz over again. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 5 Q&A Study Aid User's Guide /MS - Sequential Mode --------------------- The sequential mode option tells Q&ASA that you wish to answer the questions in the same order as they appear in the database file. When selected, the new mode will appear in the scoring window. This option does NOT cause Q&ASA to start reading from the beginning of the file; it simply changes the method used to determine the next question. This allows switching between modes. When all questions have been answered, Q&ASA will update the optional score file and display the final score. Note that this command may be locked out by an option given in the database definition file. If this is the case, the command will simply be ignored. No warning will be given indicating the command is locked out. /MA - Pseudorandom Mode ----------------------- This mode is used when you want Q&ASA to choose the questions at random. The random number generator is seeded on each invocation of Q&ASA by using the BIOS time-of-day clock to insure that the pseudorandom sequence is different each time the program is run. In this mode, Q&ASA will select the next question at random from the set of unanswered questions. It will not, therefore, ask a question twice. When all questions have been answered, Q&ASA will update the optional score file and display the final score. Note that this command may be locked out by an option given in the database definition file. If this is the case, the command will simply be ignored. No warning will be given indicating the command is locked out. /MC - Clear ----------- Use the Clear option to reset your score back to zero and to reset the question index back to the beginning of the file. The question index is cleared only here and when the database is initially loaded. Note that this command may be locked out by an option given in the database definition file. If this is the case, the command will simply be ignored. No warning will be given indicating the command is locked out. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 6 Q&A Study Aid User's Guide /N - Name --------- This command is used to enter your name, which is placed into the score file and also displayed when the session is completed. When this command is given, a data entry window will pop up and prompt for your name and any other identifying information. You may enter up to 35 characters. If you have not given your name when the session is terminated, Q&ASA will force you to enter it before you will be permitted to enter any other command. /SF - Select FAST Screen Mode ----------------------------- This command selects the FAST screen mode. In this mode, Q&ASA will not wait for any screen synchronizing signals, thereby updating the screen at the fastest possible rate. This is the default screen mode, and may cause 'snow' when used with CGA graphics cards. /SM - Select MEDIUM Screen Mode ------------------------------- This command instructs Q&ASA to write to the screen only during the horizontal blanking interval. It will slow down the screen somewhat, but may be used to minimize the effects of 'snow'. /SS - Select SLOW Screen Mode ----------------------------- This is the slowest of the three screen updating modes. It instructs Q&ASA to update the screen only during the vertical blanking interval. It will eliminate all effects of 'snow'. Scoring Window -------------- The scoring window always shows the current state of both you and Q&ASA. The items that appear in the scoring window are described below. Time Left This shows the time remaining to answer all questions in the database. It will be blank until you load a database with the /FS command. If the database has a time limit associated with it, you will see this time counting down to zero. At zero, it will change to 'Time Out'. If the database has Copyright (C) 1987, 1988 Quid Pro Quo Software Page 7 Q&A Study Aid User's Guide no time limit, this will be displayed as 'No Limit'. Mode This is the current question-indexing mode, and will be "Random" or "Sequential". Q&ASA always starts up in sequential mode. Questions When a database has been loaded, this represents the total number of questions in the database. Answered Tells the number of questions that you have answered. When it equals the number of questions in the database, you final score will be displayed. Correct This is the number of questions that you have answered correctly. Score Your score is a simple ratio of the number of possible points to the number you have been awarded, and is displayed in percent. Answering Questions ------------------- Q&ASA no longer requires you to answer questions in the order Q&ASA presents them (as defined by the mode). Q&ASA will determine the next question using the mode you select, but once the question is displayed, you may elect to skip it (intending to come back to it later) and let Q&ASA present the next one. Skipping a question is done simply by pressing the ESCape key when Q&ASA prompts for an answer. The question will not be scored, but Q&ASA will present it again after you have answered all of the remaining questions. You may not omit a question, but you may essentially scan through the questions and answer them in the order you choose. If you choose to answer a question, you must enter a response. Q&ASA will not accept a blank answer. Q&ASA will always display the number of points you will be awarded if you answer correctly at the right of the answer window. The number of points displayed is the ratio of the total number of points to the weight of the question in points, defined in the compiled database. If you answer incorrectly, you are awarded zero points. Creating a Database ------------------- The database is the heart of Q&ASA. Q&ASA receives virtually all of the information it needs to present and score your answers from the database. The database is created from a plain ASCII, or 'flat' file, and then Copyright (C) 1987, 1988 Quid Pro Quo Software Page 8 Q&A Study Aid User's Guide compiled using the database compiler Q&AC. The input given to Q&AC is called the database definition file; the output of Q&AC is the compiled database. Q&AC creates and destroys one intermediate file as it compiles the database definition file. Q&AC supports a large number of options that may be used to control the quiz session. Each option is specified using a keyword followed by zero or more lines of text. It is important to remember that keywords must be on a line by themselves with no other text. If you use a word processor program to create the database definition file, be sure to use its 'nondocument' mode to insure that it won't put in any formatting codes. A plain ASCII text editor is recommended. To enable Q&ASA to handle all of the common question formats except 'essay' questions, a very general database arrangement is used. Q&AC expects each question to be followed by the correct answer, which it uses to check the answer typed in by the user. Q&ASA can handle multiple-choice, true/false, and fill-in-the-blank questions with equal ease. The database must contain one instance of each of two keywords for each question in the database. These keywords are, exactly, in quotes: "Q=" "A=" As you might expect, these stand for "question" and "answer". The question MUST precede the answer. Q&AC will complain about any irregularities it finds in the database when it constructs the compiled database file. The following is a simple example of a question and answer as they might appear in the database definition file. It is a multiple-choice question. The following text is entered into the database definition file: Q= Multiple-choice: What is the capital of Pennsylvania? A. Philadelphia B. Washington, D.C. C. Harrisburg D. None of the above A= C Considering Q&AC and Q&ASA together as a unit, what will happen is that Q&ASA will display the question beginning on the line immediately following the 'Q=' line. The end of the question is marked by the 'A='. All lines between these markers form the question, which Q&ASA will display exactly as it appears in the database. You may, therefore, Copyright (C) 1987, 1988 Quid Pro Quo Software Page 9 Q&A Study Aid User's Guide format your questions any way that you wish. Q&ASA will impose NO restrictions other than the number of lines; you may use up to 15 lines. If the question is longer than that, the extra lines will be discarded. Blank lines between the end of the actual question and the 'A=' line are effectively discarded. Note that the 'Multiple-choice' prompt is actually a part of the database - NOT hard-coded into Q&ASA. You may include this as part of your database or omit it if you wish. The answer follows beginning on the line immediately after the 'A='. In this example, it is 'C'. All this means is that Q&ASA will score as correct any response to the question that is exactly 'C' OR 'c' - case is insignificant. Q&ASA does some preformatting of these strings prior to the comparison, however. Both the answer in the database and the answer typed in by you are processed the same way: 1. All leading whitespace is removed. This means that C and C are equivalent and are themselves equivalent to the 'C' in the example above. 2. All trailing whitespace, including newline characters, is removed. 3. All whitespace (blanks and tabs) between words is collapsed to a single space; "hello there" and "hello there" are equivalent. 4. All characters are folded to uppercase; 'Yes' and 'yes' are therefore equivalent. These steps insure that a response will not be scored as incorrect due to the position of any part of the response in either your answer or that in the database. Note that these same rules are also applied to the 'Q=' and 'A=' markers. They may, therefore, appear anywhere on the line. You cannot, however, insert anything between 'Q' and '='; nor can you put anything else on the line with the marker. In the example above, one correct answer was specified. The only answer that will be scored as correct is 'C' (and 'c', of course). Note that we could just as well have used numbers as selectors and given '3' as the answer. Q&ASA makes no attempt to interpret this information; it simply looks for an exact match based on the criteria outlined above. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 10 Q&A Study Aid User's Guide This next example will demonstrate a true/false question. Q= Answer true or false: Q&ASA understands the information in the database. A= False Note the (legal) position of the 'A='. This time we have indented the question using tabs. When Q&AC compiles the question, it expand the tabs automatically to maintain the alignment as it is in the database definition file. We also have three blank lines after the 'Q='; this serves to shift the question down toward the center of the question window to make it look nicer. This example is not good practice (although it will be compiled correctly), since the 'A=' would be easy to miss if the database were edited, and the indentation is inconsistent. It does, however, have a more serious drawback: to get the question right, you must type in 'false', all 5 characters - and 'false' is one word I just cannot type (it always comes out 'flase')! For a true/false question, one would be likely to respond with 'T', 'F', 'yes', 'y', or possibly '1' and '0'. To accommodate these options, Q&ASA allows more than one correct answer. In fact, every nonblank line between 'A=' and the next 'Q=' is a correct answer. The second example above, then, would be more appropriately given by Q= Answer true or false: Q&ASA understands the information in the database. A= False F No N 0 This permits any of the five answers to be regarded as correct. If you give an incorrect response to a question or one that is not among the list of correct answers, Q&ASA will display the correct Copyright (C) 1987, 1988 Quid Pro Quo Software Page 11 Q&A Study Aid User's Guide answer for you (as well as omit a point from your score). When Q&ASA displays the correct answer, it uses the first one given in the answer list (blank lines are ignored). What this means is that Q&ASA will display Incorrect. The correct answer is False Press any key to continue. which is more formal than 'N', for example. This feature adds a lot of versatility to Q&ASA. Since Q&ASA is intended to be a study aid, it should provide reinforcement of incorrect answers by permitting a more complete correct answer. To demonstrate this, we'll use a third example; this time, a fill-in-the- blank question: Q= The speed of light is ______ km/sec. A= Light travels at 300,000 km/sec. 300000 300,000 300K In this example, an incorrect response will elicit Incorrect. The correct answer is Light travels at 300,000 km/sec. Press any key to continue. Of course, this is also a correct answer in itself, but not a likely one. If you do enter it, it will be scored as correct. You would, however, be required to include the period. There are three more plausible correct answers that Q&ASA would consider to be correct. Any one of them is sufficient to credit the answer to you. When creating a large database definition file, it is annoying to have to type the four or more common answers to a true/false question. To make this easier, Q&AC supports simple macros. A macro is a block of text that is inserted in place of the macro identifier. We may therefore create a macro for 'true' and a macro for 'false', and use the macro identifier instead of typing all four answer lines. These macros would look something like this: M= $TRUE$ true t yes y Copyright (C) 1987, 1988 Quid Pro Quo Software Page 12 Q&A Study Aid User's Guide M= $FALSE$ false f no n Q= Answer true or false: Q&ASA understands the information in the database. A= $FALSE$ The "M=" is the macro keyword and tells Q&AC that the following lines form a macro definition. The first line following the macro keyword is the macro identifier. You may use any character string as a macro identifier, provided it does not contain blanks or tabs. The dollar signs are not necessary, but serve nicely to identify $FALSE$ as a macro invocation. When Q&AC reads the identifier, it will substitute all lines following the macro identifier up to the first blank line or keyword, whichever is found first. Note that Q&ASA will display "false" as the correct answer if the question is answered incorrectly, as it is the first answer in the answer list formed by expanding the macro. The above is a short introduction to creating a database definition file. The following section describes the Q&AC compiler in detail. The Q&AC Database Compiler ------------------------- Q&AC is a separate program that is used only when a database is first created. Once the database definition file has been created, it is compiled with Q&AC, and the compiled database file (which has an extension of .Q&A) is distributed to the users of the Q&ASA program. This offers several advantages, among them: 1. The database is encrypted. A user of Q&ASA cannot look in the file using any viewing, listing, or debugging program and see the questions and answers. Q&ASA knows the encryption method and decrypts the database as it reads it. 2. The author of the database definition file may specify a number of options to control the quiz session. These options cannot be seen or modified by the user of Q&ASA. 3. Since the database has been preprocessed by Q&AC, loading and display of questions is faster. It is not necessary to perform any formatting at run time. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 13 Q&A Study Aid User's Guide Using Q&AC --------- Q&AC has a simple invocation syntax, as follows: Q&AC <database definition filename> <ENTER> There are no command-line options. Q&AC expects you to use an extension of .DEF for the database definition file. If you use this extension, you do not have to type it. If you use any other extension, you must specify the entire filename. For example, the sample database definition file is called SAMPLE.DEF. To compile it, type Q&AC SAMPLE <ENTER> If the database definition file were named SAMPLE.TXT, however, you will be required to type Q&AC SAMPLE.TXT <ENTER> If you give the database definition file an extension of .Q&A, Q&AC will reject it, as this extension is reserved for compiled database files. The reason this extension is reserved is so that Q&ASA may filter the files in the directory when it displays the available databases. Q&AC will not make any changes to the database definition file. It will create a compiled database file of the same base name, but with an extension of .Q&A. In the examples above, the compiled database files would all be named SAMPLE.Q&A. If the compiled database file already exists, it is overwritten by Q&AC, and the original contents will be lost. Q&AC will NOT warn you of this. When Q&AC is finished, it will display the options you selected in the definition file. The output on the following page was produced by compiling the sample database SAMPLE.DEF. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 14 Q&A Study Aid User's Guide Q&A Study Aid Database Compiler Version 1.3 (SHAREWARE) Copyright (C) 1988 Quid Pro Quo Software. All Rights Reserved. File SAMPLE.DEF compiled to file SAMPLE.Q&A Configuration Name ............... "Sample Database" Total weight ....... 29 Score filename ..... "q&a.scr" Time limit ......... 00:05:00 Mode lock .......... (none) Clear command ...... Enabled Macros $FALSE$ $TRUE$ 345 Source lines 20 Questions Q&AC Language Syntax -------------------- Q&AC, being a true compiler, requires that you follow certain syntactical rules when creating a database definition file. The syntax was made as simple and forgiving as possible to minimize the learning time. The Q&AC language is line-oriented, meaning that Q&AC views its input in terms of whole lines. You may not, therefore, put two keyword markers on the same line, for example. The following is a short summary of the keywords that Q&AC uses. Q= question text A= answer list N= quiz name M= macro definition T= time limit C= clear NOT allowed S= lock in sequential mode R= lock in random mode F= output score filename W= assign weighting Each of these keywords is described in the following paragraphs. Q&AC scans and discards all text in the database definition file that is not part of a keyword interpretation. This means that you may insert comments almost anywhere, without using special comment delimiters. Since Q&AC is line-oriented, you may not, of course, place a comment on Copyright (C) 1987, 1988 Quid Pro Quo Software Page 15 Q&A Study Aid User's Guide the same line with any keyword or its associated text. Comments are otherwise unrestricted. The Q= and A= Keywords ---------------------- As mentioned previously, Q= and A= are the keywords for 'question' and 'answer', respectively. Each has the same basic syntax: Q= (or A=) <text> <text> <text> <termination> For all Q&AC keywords that take multiple lines of text as arguments, with the single exception of the Q= keyword, the <termination> is the same: a blank line, another keyword, or end-of-file. For the Q= keyword, a blank line is NOT a termination; only the 'A=' keyword terminates a question. This is to allow blank lines in the question text. You must be careful not to place comment lines immediately after the text for a question, since it will be regarded as part of the question and displayed on the Q&ASA screen. A question may not have more than 15 lines of text associated with it, and you are limited to 76 characters per line. Within this rectangular boundary, you are unrestricted. If you exceed the allowed number of lines or if a line contains more than 76 characters (after tab and macro expansion), Q&AC will display an error message and stop. You are permitted any number of answer lines, limited only by the amount of memory available in the PC running Q&ASA. If the PC has 128K bytes or more of available memory (free memory above DOS and all TSRs), you are essentially unrestricted unless your database is especially large. The N= Keyword -------------- The N= keyword is used to specify the quiz name. The name must appear on the line following the keyword, and may be up to 70 characters in length. When the database is loaded into Q&ASA, this name appears in the top border of the center (question) window. For example, to name a quiz on American history as such, you would use N= American History Quiz Copyright (C) 1987, 1988 Quid Pro Quo Software Page 16 Q&A Study Aid User's Guide The M= Keyword -------------- The M= keyword is the macro definition keyword, and indicates to Q&AC that the following lines are a macro definition. The macro definition takes the following form: M= <macro identifier> <first macro line> <second macro line> <Nth macro line> <termination> Macros are expanded recursively, so if you place the macro identifier in any of the macro definition lines, you will create a self- referential macro that will be expanded endlessly. The recursion is allowed so that you may build complex macros from simple ones if you wish. For example, to build a macro for 'TRUE' from two other macros, we could use: M= $T$ True T M= $Y$ Yes Y M= $TRUE$ $T$ $Y$ We have defined three macros, "$T$", "$Y$", and "$TRUE$". If Q&AC encounters $TRUE$ in the database definition file, it will replace it with True T Yes Y because "True" and "T" are expansions of $T$ and "Yes" and "Y" are expansions of $Y$. Note that blank lines are unnecessary between the macro definitions, since each is terminated by the M= keyword of the following macro. You may use a macro identifier anywhere in the database definition file except within its own definition, as has been pointed out. However, macros invocations MUST be surrounded by whitespace. For example, many multiple-choice questions may use the blanket selectors "none of the Copyright (C) 1987, 1988 Quid Pro Quo Software Page 17 Q&A Study Aid User's Guide above" and "all of the above". You may therefore use the following macros: M= $NONE$ None of the above. M= $ALL$ All of the above. and write a multiple-choice question as: Q= Multiple-choice: In what year did Christopher Columbus land in the New World? 1. 1592 2. 1492 3. 1066 4. $NONE$ 5. $ALL$ A= 2. 1492 2 1492 Q&AC will expand this to: Q= Multiple-choice: In what year did Christopher Columbus land in the New World? 1. 1592 2. 1492 3. 1066 4. None of the above. 5. All of the above. A= 2. 1492 2 1492 Copyright (C) 1987, 1988 Quid Pro Quo Software Page 18 Q&A Study Aid User's Guide Remember that Q&AC is line-oriented, however. If you put the following in the database definition file: M= $NW$ New World Q= Multiple-choice: In what year did Christopher Columbus land in the $NW$? 1. 1592 2. 1492 3. 1066 4. None of the above. 5. All of the above. Q&AC will NOT expand it because there is no whitespace between the $NW$ and the '?'. If, however, you use M= $NW$ New World Q= Multiple-choice: In what year did Christopher Columbus land in the $NW$ ? 1. 1592 2. 1492 3. 1066 4. None of the above. 5. All of the above. Q&AC will expand it to Q= Multiple-choice: In what year did Christopher Columbus land in the New World ? 1. 1592 2. 1492 3. 1066 4. None of the above. 5. All of the above. because the macro definition includes the newline. You should not, therefore, attempt to use a macro in the middle of a block of text. Macros must be defined before they can be used. If you place a macro definition in the middle of the database definition file and use the Copyright (C) 1987, 1988 Quid Pro Quo Software Page 19 Q&A Study Aid User's Guide macro identifier before and after it, then the identifiers that appear before the macro definition will NOT be expanded. Define all of your macros before entering the first question. The T= Keyword -------------- This is the time limit keyword. Include it in the database definition file to specify a time limit. If you omit it, the time limit is infinite. The syntax is as follows: T= HH:MM:SS where HH is hours, MM is minutes, and SS is seconds. If the time limit is less than an hour, you may omit the hours field; similarly, if the time limit is less than a minute, you may omit the hours and minutes fields. The sample database definition file contains a 5-minute timeout, given by T= 5:00 The C= Keyword -------------- This keyword is used to disable the Clear command. An individual taking a quiz with Q&ASA can use the Clear command to reset the score and essentially do the quiz twice. The author of the database definition file may prevent this by entering C= in the database definition file. When this is done, Q&ASA will ignore the Clear command completely. Note that if the Clear command is allowed, by omission of the C= keyword, and the score file is enabled with the F= keyword (described later), then a score record will be written to the score file indicating that the user cleared the score and restarted the quiz. The S= and R= Keywords ---------------------- These are the mode lock keywords, where S= stands for "sequential" and R= stands for "random". These keywords are mutually exclusive; a database definition may not contain both keywords. If it does, an error will be generated by Q&AC and compilation will stop. These keywords are used to lock Q&ASA in the mode specified by the Copyright (C) 1987, 1988 Quid Pro Quo Software Page 20 Q&A Study Aid User's Guide keyword. If you do not give either keyword, then the user of Q&ASA is able to use the Mode command to change modes. For example, to lock Q&ASA in sequential mode, use the following: S= and to lock Q&ASA in random mode: R= There are no other arguments. The lock remains in effect until another database is loaded. The F= Keyword -------------- The F= keyword controls logging of score information to a disk file. Logging is enabled by specifying a filename with the F= keyword, and disabled if you omit the keyword. The filename you specify may be any valid DOS pathname, up to 64 characters in length. All scoring records are appended to the file if it already exists, and the file will be created automatically if it does not exist. The score logging file may exist on a file server of a networked system if desired. However, Q&ASA DOES NOT SUPPORT FILE SHARING. Typically, and networked system will require that a file be locked while it is being updated so that no other network user may access the file until the updating has been completed. If Q&ASA is used in a networked system, the networking extensions to DOS must provide this function. If networking is to be used, but the network does not perform locking on a file level (such as Corvus System's OmniNet(c)), then you should specify a score logging file on the local drive of each PC, and collect these files at a later time. Otherwise, you may end up with a corrupted score file. All score log records are plain ASCII. An example is reproduced on the following page. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 21 Q&A Study Aid User's Guide Student Name: John Q. Public Database Name: Sample Database Final Score: 72.41% Termination: TIME LIMIT Started: Sun Mar 20 15:44:44 1988 Completed: Sun Mar 20 15:46:45 1988 Elapsed Time: 00:02:00 Database File: SAMPLE.Q&A Total Questions: 20 Possible Points: 29 Points Awarded: 21 Point Matrix: 1 2 3 4 5 6 7 8 9 10 0001-0010 10.34 3.45 3.45 ??? 3.45 --- ??? --- 3.45 3.45 0011-0020 6.90 3.45 6.90 3.45 --- 3.45 3.45 6.90 3.45 6.90 ********************************************************************** The '*****....*****' forms a separator between individual records. The first block contains summary information regarding the quiz session. The quiz taker's name is listed along with the name of the database (given by the N= keyword), the final score, and the reason the score record was written to the score file. In this example, it is given as 'TIME LIMIT'. This means that the quiz taker used up the time allotted by the T= keyword. The possible reasons for termination are: Completed The user answered all questions in the time allotted by the T= keyword. TIME LIMIT The user exceeded the time allotted by the T= keyword. This reason can only be produced if a time limit was given. ABORTED This indicates that the user quit the Q&ASA session before answering all questions using the /FX command. CLEARED The Clear command (/MC) was used to clear the score and restart the quiz. This reason cannot be produced if the C= keyword is used to disable the Clear command. RELOADED The user reloaded the database or loaded a different database before all questions were answered. The final score is always the ratio of the number of possible points to the total number of points awarded by answering correctly. Questions Copyright (C) 1987, 1988 Quid Pro Quo Software Page 22 Q&A Study Aid User's Guide that were not answered are scored as incorrect. The log record also specifies the time the database was loaded (thereby starting the timer, if a time limit was given), the time the quiz was completed or stopped (for any of the reasons given above), and the elapsed time. With this information and a low score due to incorrect answers, it would be relatively easy to spot random guessing. The third block of the record gives the name of the compiled database file, the number of questions in the file, and the number of possible points with the number of points awarded. Because Q&AC and Q&ASA support weighting, the number of possible points may be different from the number of questions. The last block is the point matrix. This shows the results of each question in the database, ten questions per line. Each question may have three possible outcomes: 1. The question was answered, and answered correctly. The point matrix will show the number of points awarded as a ratio of the number of possible points. 2. The question was answered, but answered incorrectly. The point matrix will show that no points were awarded with '---'. 3. The question was not answered, either by skipping over it or by exceeding the allotted time. The point matrix will show this with '???'. No points were awarded. In the example score record shown above, you can see that questions 6, 8, and 15 were answered incorrectly, questions 4 and 7 were not answered (due to the time limit given as the reason), and the remaining 15 questions were answered correctly. The point breakdown will be described the following section on weighting. The W= Keyword -------------- This keyword is used to assign weights to each question. The weighting system you use is entirely arbitrary and up to you. Q&AC and Q&ASA impose only the restriction that you use integer weights, and that you use numbers between 1 and 32767 inclusive. The syntax of the W= keyword is as follows: W= <weight> When Q&AC encounters this keyword, it reads the weight and assigns it to all the questions that follow it. If Q&AC encounters the W= keyword again, it will change the weight to the new weight, and assign the new weight to all following questions. As each question is processed by Q&AC, Q&AC keeps track of the total weight. When Q&ASA scores a question, it determines the point score to be the ratio of the total Copyright (C) 1987, 1988 Quid Pro Quo Software Page 23 Q&A Study Aid User's Guide weight to that of the question in percent. This point score is added to the running score shown in the scoring window, and also appears in the point matrix in the score file. If you do not specify a weight anywhere in the database definition file, all questions will be weighted as one point by default. Note that this arrangement allows you total flexibility in setting up a weighting system. You do not have to weight each question as a fraction of 100, for example. Q&AC and Q&ASA do this for you. The sample database weights each 'fill-in' question as three points, each true/false as 2 points, and each multiple-choice question as one point. There is one 'fill-in' question, 7 'true/false' questions, and 12 'multiple-choice' questions. The points are calculated as follows: fill-in 1 times 3 points = 3 points true/false 7 times 2 points = 14 points multiple-choice 12 times 1 point = 12 points Total: 20 29 There are therefore 29 possible points (as shown in the score file). A 'fill-in' question is therefore worth 3/29 points or 10.34 points relative to 100. A 'true/false' question is worth 2/29 points or 6.90 points relative to 100, and a 'multiple-choice' question 1/29 or 3.45 points relative to 100. In the example score record, the user was awarded a total of 21 out of 29 possible points, for a score of 21/29 or 72.41%. Adding all of the points shown in the point matrix will produce the same result. Conclusion ---------- Most of these examples can be found in the sample database definition file, SAMPLE.DEF. Experiment with it (remember to recompile it with Q&AC if you change it), but please don't pass on a modified copy to someone else. The author Copyright (C) 1987, 1988 Quid Pro Quo Software Page 24 Q&A Study Aid User's Guide Appendix -------- Q&AC Error Messages ------------------- Usage: Q&AC <definition filename> This error will be generated if you invoke Q&AC without specifying the name of a database definition file. Illegal definition filename: <filename> This error is generated if you supply a database definition file with an extension of .Q&A. Cannot find database definition file <filename> This error indicates that Q&AC was not able to open the database definition file you specified. Unable to create temporary file <filename> This error indicates that Q&AC was not able to create its intermediate temporary file. File <def file> : Line <line> : Answer omitted You specified a question without an accompanying answer, or your syntax is such that Q&AC could not determine where the answer is. File <definition file> : Line <line> : Question omitted You specified an answer without a preceding question, or your syntax was such that Q&AC could not determine where the question is. File <def file> : Line <line> : Macro name missing You specified the macro definition keyword M=, but the next line is blank. File <def file> : Line <line> : Weight definition missing You specified the weighting keyword W=, but the next line is blank. File <def file> : Line <line> : Invalid weight You specified a weight that was outside the range 1..32767 or entered alphabetical characters. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 25 Q&A Study Aid User's Guide File <def file> : Line <line> : Title missing You specified the name keyword N=, but the next line is blank. File <def file> : Line <line> : Title too long - truncated The name you entered after the N= keyword is longer than 70 characters. File <def file> : Line <line> : Time limit definition missing You specified the time limit keyword T=, but the next line is blank. File <def file> : Line <line> : Invalid time limit The time limit you specified following the T= keyword is not in the form HH:MM:SS. File <def file> : Line <line> : Mode lock already set You specified S= and R= in the same definition file. Q&AC is complaining about the second occurrence. File <def file> : Line <line> : Filename missing You specified an output score file with the F= keyword, but the next line is blank. File <def file> : Line <line> : Illegal filename You specified a filename after the F= keyword that has invalid characters or longer than 64 characters. File <def file> : Line <line> : Question line exceeds 76 characters You entered a line in a question block that will not fit into Q&ASA's window. File <def file> : Line <line> : Question exceeds 15 lines You entered a question that has too many lines. File <def file> : Line <line> : Answer line exceeds 76 characters You entered an answer line that will not fit into Q&ASA's answer window. Cannot create database output file <filename> Q&AC was unable to create the compiled database output file. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 26 Q&A Study Aid User's Guide Cannot open temporary file <filename> Q&AC was unable to create its temporary file. File <def file> : Line <line> : Insufficient memory Q&AC ran out of memory while processing your database. If this happens, you have several options. You may: 1. Reduce the number of questions or split the database into two files. 2. Reduce the number of macros. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 27 Q&A Study Aid User's Guide COPYRIGHT This program is copyright (C) 1987, 1988 by Hal Endresen, Quid Pro Quo Software. All rights reserved. Q&A Study Aid is distributed as SHAREWARE, or User-Supported Software. I encourage you to try the program and share it with friends, provided that: The program is distributed in unmodified form as the complete archive STDYAID2.ARC, complete with documentation and this registration form. No fee, charge or other consideration is requested or accepted. The program is not distributed in conjunction with any other product. REGISTRATION ------------ If you intend to use Q&A Study Aid on a regular basis, please register it and show your support for the author. Commercial, business or governmental use by non-registered users is prohibited. Q&A STUDY AID REGISTRATION FORM ------------------------------- Name __________________________________________________________ Address _______________________________________________________ City _____________________________ State ______ Zip __________ Phone _________________________________________________________ To register, send this form and a check for $20 to: Quid Pro Quo Software 1703 Marlbrook Lane Lansdale, PA 19446 Registered users will receive notification of upgrades of Q&A Study Aid. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 28 Q&A Study Aid User's Guide USER SUPPORTED SOFTWARE ----------------------- The user supported software concept (usually referred to as SHAREWARE) is an attempt to provide software at low cost. The cost of offering a new product by conventional means is staggering, and hence dissuades many independent authors and small companies from developing and promoting their ideas. User supported software is an attempt to develop a new marketing channel, where products can be introduced at low cost. If user supported software works, then everyone will benefit. The user will benefit by receiving quality products at low cost, and by being able to "test drive" software thoroughly before purchasing it. The author benefits by being able to enter the commercial software arena without first needing large sources of venture capital. But it can only work with your support. If you find that you are still using Q&A Study Aid after a couple of weeks, then obviously it is worth something to you, and you should register. Copyright (C) 1987, 1988 Quid Pro Quo Software Page 29