home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
HAM Radio 1
/
HamRadio.cdr
/
misc
/
studyaid
/
q&asa.doc
< prev
next >
Wrap
Text File
|
1988-08-07
|
66KB
|
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
