             Drill Designer For DOS and Windows 1.0:  User's Manual


     The original version of Drill Designer (Macintosh version) was created in 
Fall 1990 by members of the Instructional Software Development Group (ISDG) 
at Weeg Computing Center, The University Of Iowa, in a collaborative effort 
with:

                    Stephen M. Alessi, Associate Professor,
                   Psychological And Quantitative Foundations

                  James P. Pusack, Associate Professor, German

                  Sue K. Otto, Director, Language Media Center

     Members of ISDG are:

                Stephen W. Wessels, Manager Software Development
                       Les J. Finken, Sr. Systems Analyst
                      Steven N. Bowers, Sr. Systems Analyst
                         Derek Siebert, Project Analyst
                        Dave Priebe, Programmer/Analyst
                     Patti P. Santangelo, Programmer/Analyst

     Participating ISDG members on the Macintosh version were:

          Co-Project Leaders:  Bowers, Finken
          External Specifications:  Bowers, Finken, Siebert
          Internal Specifications:  Siebert, Bowers
          Implementation:  Siebert
          Testing:  Siebert, Santangelo
          Documentation:  Siebert, Bowers

     ISDG members participating on the DOS/Windows version were:  Bowers

     Credit for the instructional design theory upon which Drill Designer is 
based goes to Stephen Alessi and Stanley Trollip (refer to Computer-Based 
Instruction:  Methods and Development, Prentice-Hall, 1991).

     Further, it should be mentioned that an older software package exists that 
is based upon these same instructional design theories.  The 1985 publication 
Drill Shell (CONDUIT, The University Of Iowa) was a completely separate and 
distinct package for the Apple IIe containing importable BASIC source code 
pieces that aid drill development in Apple BASIC.  This package provided much 
assistance in clarifying issues during the early design phases of Drill 
Designer for Macintosh.  

                     Copyright 1994 The University of Iowa.
                               Table of Contents


Introduction to Drill Designer .......................................3

Getting Started:
     Hardware and Software Requirements ..............................4
     Contents of the Distribution Disk ...............................5
     Installing Drill Designer .......................................6
     Drill Author's Responsibilities .................................8

Using Drill Designer:
     Simple Drill Program Flow ......................................11
     Notes on Parameter Formats .....................................12

Simple Drill Commands:
     CreateDrill ....................................................13
     Dispose ........................................................17
     GetErrorMessage ................................................18
     Next ...........................................................19
     Correct ........................................................20
     Incorrect ......................................................21

Commands for Retaining Student Performance Information:
     Store ..........................................................23
     Restore ........................................................25
     GetAuthorVariables .............................................26

Drill Modification Commands:
     Insert .........................................................27
     Purge ..........................................................28
     Requeue ........................................................29
     Retire .........................................................30
     Pad ............................................................31
     RetrieveInfo ...................................................32

Appendix A:  Error Messages List ....................................35
Appendix B:  Store and Restore File Map .............................39

                                    - 3 -

                         Introduction to Drill Designer

     Drill Designer is a set of commands and functions that allow easy and 
flexible drill handling for quizzing and testing applications.  It facilitates 
the creation of a list of questions (or items) and the subsequent modification 
of that list based on correct and incorrect responses from a student or user.  
When these commands are included in a ToolBook book, an Authorware course, a 
C program, etc., they remove the "busywork" of drill making and add features 
that can automatically provide for extra help on the items that are missed 
most often, thereby increasing the effectiveness of the drill.
     The future queue is the list of questions to be given.  It does not 
contain the question itself, only a question number that the author indexes 
with his/her list of questions.  Initially, the future queue is created from 
the long list, a list of all the questions that can be presented.  Additional 
questions can then be drawn from this list if desired.  When a student 
successfully answers all occurrences of a given question in the future queue, 
that question is added to the retired items list. 
     Drill Designer uses "Variable Interval Performance Queuing" to provide 
additional practice on questions answered incorrectly.  Basically this means 
that when a question is missed, all occurrences of this question are removed 
from the future queue.  The question is then reinserted at positions chosen 
by the author.  Generally, an author arranges these positions so that the 
distance between positions increases; thus, the question may be presented 
again fairly soon, then a bit later, and then quite a bit later.  In this way 
the student will remember the answer in short-term memory and is gradually 
forced to commit it to long-term memory.
     As the future queue gets smaller, it may not be long enough to allow the 
insertions to be made at the positions specified.  In these instances, Drill 
Designer uses several methods to lengthen the future queue or modify the 
insert positions to allow them to fit.  These vary depending on the insertion 
technique chosen by the author.
     Drill authors should have a good working knowledge of an authoring tool 
(Asymetrix ToolBook, MacroMedia Authorware Professional for Windows, etc.) or 
C, whichever will be used to produce drills.  To use Drill Designer 
effectively, authors should also have a good idea of how the Drill Designer 
commands operate.  The following pages give a thorough presentation of Drill 
Designer and its abilities.  It is suggested that authors read at least 
through the Basic Commands section before attempting to write an application 
that uses Drill Designer.

                                    - 4 -

                       Hardware and Software Requirements


Hardware Requirements:
     An IBM or compatible computer and the memory, hard drive, etc. required 
by Microsoft DOS and Windows and the compiler or authoring tool that you 
choose.

Software Requirements:
     Microsoft DOS 3.1 or later (5.0 or higher recommended)
     Microsoft Windows 3.1 or later (unless using C lib in DOS only)
     The C library requires Borland C++ 3.1 or higher, either the DOS or
         Windows compiler (may work with other compilers--the lib
         conforms to OMF standard)
     The DLL can be used by any DLL-capable authoring tool, e.g.:
         Asymetrix ToolBook 1.5 or higher
     The UCD is a DLL made specifically for use with:
         Macromedia Authorware Professional For Windows 2.0 or higher

     The version numbers above are examples.  It is probable that Drill 
Designer will work on some earlier versions and most later versions, but it is 
on those above that it has been tested.  

                                    - 5 -

                        Contents of the Distribution Disk

The distribution disk contains the following programs/files:

dd.dll is the dynamic link library that can be used in an Asymetrix ToolBook 
     book, etc. 
     
dd_ucd.ucd is a dynamic link library customized for use with MacroMedia 
     Authorware Professional For Windows 2.0 or higher.

dd.lib is the library to use in a Borland C++ project, etc.
dd.h is the header file that is #included in the first line of your C program.

Inside the directory demos:
dd_test.tbk is a sample ToolBook book.
dd_test.apw is a sample Authorware course.
     These programs can be used to experiment with various drill formations 
and see exactly how queues are affected by various commands.  They are also 
useful as examples of how Drill Designer is incorporated into each of the 
formats.

Inside the directory c_demo:
recycle.exe is a vanilla Windows application that uses Drill Designer to 
     present a drill on recycling, produced with Borland C++ 3.1.
recycle.c is the source code for recycle.exe; it is included to show how 
     Drill Designer is used in a C program.
recycle.prj is the Borland C++ 3.1 project for the recycle application.  It 
     shows how dd.lib is added in a Borland C++ project.
recycle.dsk is a Borland C++ 3.1 desktop file included for convenience 

Inside the directory license:
license.doc is the shareware agreement in Microsoft Word/Win 2.0 format.
license.txt is the shareware agreement in standard text format.
     Please read the license agreement as soon as possible.

                                    - 6 -

                            Installing Drill Designer

     To use the Drill Designer routines, they must be included in your C 
program or added to your ToolBook book or Authorware course.  The 
following describes how this is done in each case:


In ToolBook:

     Inside the book's enterBook handler, the DLL must be linked using 
the following statement:

   linkdll "dd.dll"
     POINTER CreateDrill(POINTER,INT,INT,INT,STRING,STRING,STRING,STRING,STRING)
     POINTER StoreDrill=Store(POINTER,STRING,STRING,STRING,STRING)
     POINTER RestoreDrill=Restore(POINTER,STRING,STRING,STRING)
     POINTER GetAuthorVariables(POINTER)
     INT NextItem=Next(POINTER)
     POINTER Correct(POINTER)
     POINTER Incorrect(POINTER)
     POINTER Requeue(POINTER,INT,STRING,STRING)
     POINTER Purge(POINTER,STRING,STRING)
     POINTER Retire(POINTER,INT)
     POINTER Insert(POINTER,INT,STRING,STRING)
     POINTER Pad(POINTER,STRING,STRING)
     LONG RetrieveInfo(POINTER,INT,INT,STRING)
     POINTER Dispose(POINTER)
     POINTER GetErrorMessage(POINTER)
   end linkdll

     Note above that Drill Designer's calls Store, Restore, and Next are also 
ToolBook OpenScript terms; the shown syntax renames these calls to StoreDrill, 
RestoreDrill, and NextItem respectively for ToolBook use.

In Authorware:

     From inside Authorware, with your course opened, look under the 
menu named Data and select Load Function.  Locate dd_ucd.ucd, select 
it, click OK.
     Another dialog box appears, displaying the name and description 
of each custom function contained in the file.  Select each of the listed 
custom functions and click Load.  Each function you selected is loaded 
and will now appear when you select Show Functions from the Data menu,
in the category named with the current filename.
                                    - 7 -

In C:

        As the first line of your program, use the following line exactly as it 
appears:

     #include "dd.h"

     Also, the library file dd.lib must be added to your Borland C++ project.  
See the recycle project (recycle.prj) on the distribution diskette for an 
example.

                                    - 8 -

                         Drill Author's Responsibilities

     Drill authors are responsible for setting up two very important 
variables:  the data pointer and the path name.  If the data pointer variable 
is not declared and initialized, Drill Designer will not function 
correctly.  If the path name is not set, the Store and Restore functions will 
not be able to locate where to store and retrieve files and will use the 
current working directory.

                                The Data Pointer

     The data pointer tells Drill Designer where to find information that it 
needs in order to execute.  In ToolBook, Authorware, and C it must be declared 
as a global variable and correctly initialized as shown below.

In ToolBook:
     Include this exact syntax in the book's enterBook handler:
          system DataPtr
          put "0,0" into DataPtr

In Authorware:
     Open your course and select Data in the menu bar.  Select New Variable 
and a box should pop up.  Type in DataPtr as the variable name and 0 (a zero) 
as the initial value.

In C:
     Declare the following in your section of global variables:

         global_ptr     DataPtr = NULL;

     global_ptr is a type declared in dd.h; this name must appear 
exactly the same in your code.

     You don't need to use the exact name "DataPtr"; something shorter may 
be better, since you must pass this variable to every Drill Designer call 
from C.  In the command syntax and examples contained in later pages, this 
variable is referred to as DataPtr; simply substitute the name you have 
used if it is different. 

                                    - 9 -

                                 The Path Name

     The path name is declared in a way similar to the data pointer 
declaration.  The explanation of <<path>> is on the following page.

In ToolBook:    
     Include the following in your book's enterBook handler:
         system PathName
         put "<<path>>" into PathName

In Authorware:  
     Select Data, then New Variable as before with DataPtr.  Type in PathName 
as the variable name.  Then for the initial value, type in "<<path>>" as 
described below.

In C:
     Put this declaration in your code (global area):

         char *PathName = "<<path>>";


                                   - 10 -

                                   <<path>>

     <<path>> is the full DOS path where you want files saved to and 
restored from.  This may consist of a drive name, and additionally any 
directories along the way to (and including) the directory you want the 
data stored into.  When Drill files are stored, everything is contained in a 
"DrillData" directory (the file extension is .DD; see Appendix B for more
information on the DrillData directory).  When you specify your path, you 
are specifying the complete path to the directory that will contain the 
DrillData directory after the Store command, and the directory in which 
Drill Designer looks for a DrillData folder when calling Restore (see Store, 
Restore, and Appendix B).
     As per DOS specifications, directories in a full path are separated 
by backslashes (\), with the first backslash representing the root directory.
     A sample path is:

         C:\DEMOS

     In this example, the "DrillData" directory will be located inside the 
     directory called "DEMOS", which exists in drive C:'s root directory.

     DOS paths can sometimes be tricky to designate correctly.  The 
following are examples of valid DOS paths:
        C:\        The root directory of drive C:
        C:\MYDIR   Directory MYDIR in C:'s root
Note that it is valid to specify the path as empty.  In this special case, 
Drill Designer defaults to the current working directory.  The following paths
are not valid DOS paths:
        C:         Just a drive specifier
        C:\MYDIR\  The ending backslash makes it invalid
        C:\THE DIR Contains a space--invalid

     Authorware users:  Newer versions of Authorware may place two 
backslashes in your string for every one you type.  This is not a problem.

     C users:  since the backslash is a special C character, don't forget 
to include 2 backslashes to get one in the path (e.g., C:\\DEMOS).

                                   - 11 -

                            Simple Drill Program Flow

     The commands CreateDrill, Dispose, GetErrorMessage, Next, Correct and 
Incorrect form the core of Drill Designer; with these six commands an author 
can create and process drills with much flexibility.  Below is a general idea 
of how a program might flow using these commands to create and utilize a 
drill.

     -CreateDrill is the command that sets everything up; thus it is usually 
         the first Drill Designer command used in a drill application.  In 
         this call the author specifies many parameters used in the creation 
         and upkeep of the drill.
     -GetErrorMessage is used often while testing a drill application during 
         its development.  Following the CreateDrill call (and any subsequent 
         calls) the result of GetErrorMessage can be tested and displayed by 
         the author to see the error messages and warnings that result from 
         the previous call.  This will help the author avoid common pitfalls 
         while making a drill application.

     Then, the flow typically becomes a loop:
     -Next returns the question number of the question to be given next.  
         The author can use this number as an index to the actual written 
         question, and then allow the student to respond in whatever way 
         the author is having users respond.  When Next returns 0, there 
         are no more questions left in the queue.

     The author determines whether the user provided the right answer, and 
         depending on this, calls either:
     -Correct, which handles correct responses by removing the front item 
         from the queue (thereby readying the next question to be 
         retrieved by Next).
     -Incorrect, which handles incorrect responses by removing the item 
         completely from the queue and reinserting it at the positions 
         specified in the CreateDrill call.  Again, the subsequent call 
         to Next will provide the next question number to be used.

     -Dispose frees the memory used by Drill Designer.  When the future queue 
         is exhausted, or the user wants to quit (or for any other reason the 
         author sees fit to end the session), the author calls Dispose.

                                   - 12 -

                             Notes on Parameter Formats

     The following is a description of the parameter types shown in the syntax 
portion of the command descriptions.  In each call, where parameters are 
necessary, a descriptor will be shown in the location where a parameter would 
be included.  This descriptor is given a name that briefly summarizes its 
function and also tells what type of parameter is expected.  The last segment 
of the descriptor name will be one of the following:

     num:   An integer or a variable containing an integer.
     str:   A string or a variable containing a string.  Strings are 
            surrounded by double quotes ("This is a string").  If this 
            is put into a C variable, it should be of type char *.
     char:  A single character or a variable containing a single character.  
            In C, a single character is surrounded by single quotes, 
            ('A', 'B', etc.).  In ToolBook or Authorware, a character 
            parameter should be a string containing a single 
            character ("F", for example).  
     list:  This specifies a certain type of string, a string of integers 
            separated by spaces.  For example, "3 6 9 12" and "17" are both 
            lists, the latter being a list of one element.  Again, in C, if 
            this is passed by a variable, it should be of type char *.

     When a command returns a value, included in the syntax listing is a 
generic method of storing the value.
     After the command syntax, each descriptor's meaning is explained as to 
its significance to the command.  Some parameters have default values that 
are used in case of a bad parameter; the default value, if there is one, 
is enclosed in brackets.


                                   - 13 -

                                  CreateDrill
Syntax:
ToolBook:               
     set DataPtr to 
     CreateDrill(DataPtr,FQnum,REPnum,QPnum,ORDchar,TECHstr,INClist,EXP1,EXP2)
Authorware:
     DataPtr :=
     CreateDrill(DataPtr,FQnum,REPnum,QPnum,ORDchar,TECHstr,INClist,EXP1,EXP2)
C:      
     CreateDrill (&DataPtr, FQnum, REPnum, QPnum, ORDchar, TECHstr, INClist,
         EXP1,EXP2);
     /* note that in C the address of DataPtr must be passed */

     FQnum:  the number of different questions to be in the future queue 
         initially.              [default = QPnum (if valid) or 20]
     REPnum:  the number of times to present the initial future queue (the 
         queue is repeated based on this number) [1]
     QPnum:  the question pool size; this is the total number of questions 
         in the drill.  This should be greater than or equal to FQnum. 
         [FQnum (if valid) or 20]
     ORDchar:  Determines the order (orientation) of the future queue and long 
         list: sequential ("S") or random ("R").    ["S"]
     TECHstr:  The insertion technique used for calls to Incorrect.  Choices 
         are: "DII", "RDII", "RDIns", "RDInt", "RFII", and "EC".  ["RFII"]
     INClist:  The list of the insert positions used for calls to Incorrect.       
         ["3 7 17"]
     EXP1 and EXP2:  Extra variable parameters to specify depending on TECHstr 
         (see below)

Variable Parameters:  Depending on the string passed in TECHstr, additional 
parameters will be necessary as follows:
         TECHstr                         extra parameters
         RFII                            (none)
         DII, RDInt                      SMLstr
         RDIns                           FEWstr
         RDII                            SMLstr, FEWstr
         EC                              RETstr, RPLlist

     SMLstr:  The smallest insertion position allowed           ["1"]
     FEWstr:  The fewest insertions allowed                     ["1"]
     RETstr:  The number of items to retire before replenishing; cannot be 
         greater than FQnum                                     ["1"]
     RPLlist:  The list of insert positions to use when replenishing         
         (see Correct)                                          ["1 3 5"]

                                   - 14 -

     CreateDrill is used to create a drill from scratch; it sets up the 
initial future queue and long list and clears everything else to zero (or 
its default).
     A call to either CreateDrill or Restore must be made before other 
operations can take place.  If CreateDrill or Restore have not been 
called, the value of DataPtr will not have been changed from its original  
value (see Drill Author's Responsibilities) and the other routines will just
beep the speaker and return without doing anything when called.  When 
finished with a drill, Dispose should be called to clear memory.
     CreateDrill first builds the long list using QPnum (question pool size) 
for the length.  If ORDchar is "S", the list is sequentially ordered; if "R", 
the list is randomized; it still contains the same numbers, but in a random order.
     The future queue is constructed by pulling items from the long list (the 
amount specified in FQnum).  These items are removed from the long list, 
leaving it shorter (and often empty; much of the time QPnum is chosen to be 
equal to FQnum).  FQnum can be 0 (zero), which may be useful if an author 
wants to build a future queue completely from scratch using the Drill 
Modification Commands.
     The future queue is then repeated based on REPnum. A value of 1 means the 
future queue is left as it is; 2 means it is doubled (i.e., repeated once), 
etc.  Thus REPnum specifies the number of times each question exists in the 
future queue at the start of the drill.  Note that if ORDchar was "R", 
repetitions of the future queue are also randomized, so that the "randomness" 
is not lost through a repeated pattern.
     TECHstr defines the insertion technique to be used: Diminishing Insertions 
and Intervals ("DII"), Resurrection with Diminishing Insertions and Intervals 
("RDII"), Resurrection with Diminishing Insertions ("RDIns"), Resurrection with 
Diminishing Intervals ("RDInt"), Resurrection with Fixed Insertions and Intervals 
("RFII") or Endless Continuum ("EC").  Based on this parameter, others may be 
needed as shown on the previous page.  More detail about the insertion 
techniques and these parameters is contained under the description of the 
Incorrect command.
     Unless the Endless Continuum ("EC") insertion technique is being used, 
the long list is not normally a factor in the drill and in most cases FQnum 
and QPnum are equivalent.  It is possible, though, to perform many operations 
on the long list regardless of the insertion technique being used; an author 
may want to start with a larger question pool while using "DII", for example, 
and use the Drill Modification Commands to have control over replenishing.
     Note that ORDchar (list order or orientation) affects the long list; the 
future queue is affected because the long list is used as the source for the 
initial future queue.  If "R" is specified with QPnum at 40 and FQnum at 20, 
the initial future queue will not contain numbers 1 through 20 in random 
order, but rather 20 numbers from 1 to 40 in a random order.  To achieve 
the former, QPnum would have to be set to 20.

                                   - 15 -

Examples:
ToolBook:
     set DataPtr to CreateDrill(DataPtr,20,2,20,"S", "RFII", "3 7 17","","")

     set DataPtr to CreateDrill(DataPtr,20,2,20,"S", "DII", "5 10 15","5","")

             Note the final parameter, "5", the smallest allowed insert 
             position.

     set DataPtr to CreateDrill(DataPtr,20,2,20,"R","RDInt","2 8","2","")

             Note the final parameter (smallest position) and the random 
             orientation.

Authorware:
     DataPtr := CreateDrill(DataPtr,20,2,20,"S","RFII","3 7 17","","")

     DataPtr := CreateDrill(DataPtr,20,2,20,"S","RDIns","1 4 8","2","")

             Note the final parameter, "2", the fewest allowable 
             insertions.

     DataPtr := CreateDrill(DataPtr,20,1,20,"S","RDII","5 8 12","4","2")

             Note the last two parameters, the smallest insert position 
             allowed and the fewest insertions allowed.

C:
     CreateDrill (&DataPtr,20,2,20,'S',"RFII","3 7 17");

             Note the single quotes surrounding the S (but the double quotes 
             remain around the list).

     CreateDrill(&DataPtr,20,2,80,'S',"EC","3 7 17",3,"2 4");

             Note the final two parameters, the number to retire before 
             replenishing and the positions to insert when replenishing.  
             Note also the larger question pool size.

     C users: note that when using dd.lib with C, EXP1 and EXP2 do not have to 
be included if not required for the call.  Further note that SMLstr, FEWstr, 
and RETstr are passed as integers to dd.lib, not as strings (see second 
example above).

                                   - 16 -

                             Drill Creation Diagram

Example (ToolBook format):
     set DataPtr to CreateDrill(DataPtr,5,3,10,"S","RFII","4 11","","")
       _______ _ _ _ _ _ _ _ _ _______                    _______
Long   |__1__|          Future |__1__|             Future |__1__|
List:  |__2__|          Queue  |__2__|             Queue  |__2__|
       |__3__|                 |__3__|                    |__3__|
       |__4__|                 |__4__|                    |__4__|
       |__5__|  _ _ _ _ _ _ _ _|__5__|                    |__5__|
       |__6__|                 _______                    |__1__|
       |__7__|          Long   |__6__|                    |__2__|
       |__8__|          List   |__7__|                    |__3__|
       |__9__|                 |__8__|                    |__4__|
       |__10_|                 |__9__|                    |__5__|
      Step 1: Build            |__10_|                    |__1__|
      the long list.         Step 2: Build                |__2__|
      Randomize if           the initial                  |__3__|
      necessary based        future queue                 |__4__|
      on ORDchar                                          |__5__|
                                                      Step 3: Repeat
                                                      the future queue
                                                      as per REPnum

                                   - 17 - 

                                    Dispose
Syntax:
ToolBook:       get Dispose(DataPtr)
Authorware:     Dispose(DataPtr)
C:              Dispose (&DataPtr);

     Dispose frees the memory used by Drill Designer, and thus should be 
called before the author's application is exited.  Failure to do so may result 
in memory fragmentation or storage problems.  Note that after disposing, 
DataPtr should be set back to a value of 0 ("0,0" in ToolBook, 0 in 
Authorware).  In C, Dispose sets DataPtr to NULL after disposing.
     Also note that when used from C, the author must pass the address of 
DataPtr (precede with the "&" character) to the Dispose function.

                                   - 18 -

                                 GetErrorMessage
Syntax:
ToolBook:       put pointerString(0,GetErrorMessage(DataPtr)) into YourStr
Authorware:     YourStr := GetErrorMessage(DataPtr)
C:              YourStr = GetErrorMessage (DataPtr);

     GetErrorMessage returns a pointer to a string containing the error 
messages that were generated by the previous Drill Designer call (with 
the Authorware UCD, the string itself is returned).  Some error messages 
mean that the previous command could not be executed, while others 
are warnings signifying that the command was executed, but certain parameters 
were not specified appropriately so defaults were used.  GetErrorMessage is 
very useful for the author while creating a drill to insure that all 
commands are recognized and that the parameters are appropriate.
     When there is no error or warning from the previous call, GetErrorMessage 
returns a pointer to a null string (or, with the UCD, a null string itself), 
and testing for a null string can tell whether there is any message.  Remember 
that there are many messages that do not mean that the command has failed.  
See Appendix A for further information.
     When used from ToolBook or Authorware, the maximum returned string length 
is 255; if the error message exceeds this length (which is unlikely if not 
impossible) it will be truncated.
     When used from C, YourStr should be of type char * , not a character 
array.
     Appendix A contains a list of all error messages and what they signify.
     Note that from ToolBook an additional function must be used to retrieve 
the actual string (pointerString, shown in the examples above).

                                    - 19 -  

                                       Next
Syntax:
ToolBook:       set YourNum to NextItem(DataPtr)
Authorware:     YourNum := Next(DataPtr)
C:              YourNum = Next (DataPtr);

     A call to Next returns the question number of the first item in the 
future queue.  This does not change the future queue in any way; repeated 
calls to Next would yield the same result.  Next is used by the author to 
determine the next question to present to the student.
     If the future queue is empty, Next returns a zero.
     Note that since Next is an OpenScript keyword, NextItem (or a similar 
name) must be used in ToolBook (see the section entitled Installing Drill 
Designer, above).
        Advanced technique: while Drill Designer has built-in routines that 
inhibit two instances of the same item from getting "side-by-side" (e.g., 2 4
5 5 8 7 ...), it may occasionally occur during the requeuing process when
the user is answering several items incorrectly.  Storing the result of Next
and comparing subsequent calls can be useful in avoiding presenting the same
question to the user twice in a row.


                                   - 20 - 

                                     Correct
Syntax:
ToolBook:       get Correct(DataPtr)
Authorware:     Correct(DataPtr)
C:              Correct (DataPtr);

     Correct is called by the author when the student correctly answers a 
question.  That item is then removed from the head of the future queue.  If 
there are no more occurrences of the item left in the future queue, the item 
is retired, i.e., it is placed into the retired items list.
     It is possible that an item to be retired already exists in the retired 
items list; in this case, the item's up-to-date data is simply copied into the 
corresponding item in the retired items list.  The position of the item in the 
retired items list does not change.  There are never multiple occurrences of 
an item in the retired items list.
     When the endless continuum ("EC") insertion technique is being used and 
enough items have been retired, replenishing occurs.  Replenishing refers to 
removing items from the front of the long list and inserting them into the 
future queue (at the positions specified by RPLlist (replenish positions) in 
the CreateDrill call).  The number of items that must be retired to trigger 
replenishing is specified in the CreateDrill call (RETnum) and the count of 
items retired is reset to zero after each replenish.
     Note that the replenish positions list ("RPLlist") is a list of positions 
in which to insert a group of items (RETnum may be larger than one).  For 
example, if five items are to be inserted into positions 3 and 6, then all five 
items will be inserted after position two, and then all five items will be 
inserted after position five.  However, position five will have moved due to 
the first insertions.  Therefore, the result of this will be that the items 
exist at positions 3, 4, 5, 6 and 7 and also at positions 10, 11, 12, 13 and 
14.  If the five items are taken as a "group" of one, then they are indeed at 
positions 3 and 6.
     Also note that the smallest replenish position allowed is 1 and that 
subsequent replenish positions should increase by at least one to ensure
that replenished groups stay together (e.g., "1 2 3").

                                   - 21 -

                                   Incorrect
Syntax:
ToolBook:       get Incorrect(DataPtr)
Authorware:     Incorrect(DataPtr)
C:              Incorrect (DataPtr);

     Incorrect is called when the student answers a question incorrectly.  
All occurrences of the item are removed from the future queue and then 
reinserted at the positions specified in the CreateDrill call ("INClist").  
     Often the future queue is not long enough to accommodate the insertions 
at the positions specified.  For example, if the specified positions are 3, 7 
and 17, and the future queue contains only 13 elements, no insertion can be 
made at position 17.  When this occurs, Drill Designer uses various methods 
to lengthen the future queue and/or decrease the specified positions in order 
to allow the insertions to be made.  These methods vary depending on the 
"insertion technique" specified in the CreateDrill call:
-Resurrection (used by "RDII", "RDIns", "RDInt", "RFII" and "EC"):  This 
     refers to the lengthening of the future queue by adding items from the 
     retired items list to the end of the future queue.  Items are resurrected 
     in reverse order, meaning that items more recently retired (and therefore 
     generally more difficult) are returned into the queue before the easier, 
     earlier-retired items.
-Diminishing Intervals (used by "DII", "RDII" and "RDInt"):  This method seeks 
     to reduce the size of the insert positions so that the insertions can be 
     made.  For example if the insert positions are 3, 7 and 17 and the length 
     of the future queue is 10, then the 17 might be reduced to allow the 
     insertions.  This method cannot make a position lower than the "smallest 
     position" (SMLnum) which is defined during CreateDrill.  
-Diminishing Insertions (used by "DII", "RDII" and "RDIns"):  In this method 
     the number of insert positions is reduced.  For example if the insert 
     positions are 3, 7 and 17 and the length of the future queue is 10, 
     then the 17 might be deleted to allow the insertions.  The number of 
     insertions can not be less than "fewest positions" (FEWnum) defined 
     during CreateDrill.
-Appending (used by "RDII", "RDInt", "RDIns", "RFII", and "EC"):  This refers 
     to the use of non-retired items to lengthen the future queue.  In this 
     case items are copied from the front of the future queue and padded to 
     the end.
                                   - 22 -

The insert techniques operate as follows:
-"DII" (Diminishing Insertions and Intervals):
     Because this technique includes no methods for lengthening the future 
     queue, it comes with a special case:  if the length of the future queue 
     is too small to allow the first insertion, then one insertion is made at 
     the end of the future queue and the algorithm ends.  Otherwise, this 
     technique uses Diminishing Intervals and Diminishing Insertions (but it 
     does not check "fewest positions" before deleting an insert position).

-"RDII" (Resurrection with Diminishing Insertions and Intervals):
     This technique uses Resurrection, Diminishing Intervals, Diminishing 
     Insertions, and Appending.

-"RDIns" (Resurrection with Diminishing Insertions):
     This technique uses Resurrection, Diminishing Insertions and Appending.

-"RDInt" (Resurrection with Diminishing Intervals):
     This technique uses Resurrection, Diminishing Intervals and Appending.

-"RFII" (Resurrection with Fixed Insertions and Intervals):
     This technique uses Resurrection and Appending until the insertions 
     can be made in the specified positions.

-"EC" (Endless Continuum):
     This technique works the same way as "RFII" above.  The difference in 
     this technique comes during calls to Correct where it replenishes 
     from the long list (see Correct).

                                   - 23 -  

                                     Store
Syntax:
ToolBook:       get StoreDrill(DataPtr,PathName,STUstr,DRLstr,AUTHstr)
Authorware:     Store(DataPtr,PathName,STUstr,DRLstr,AUTHstr)
C:              Store (DataPtr, PathName, STUstr, DRLstr, AUTHstr)

     STUstr: the student ID (<= 8 characters)        [def. = null string]
     DRLstr: the drill ID (<= 8 characters)          [null string]
     AUTHstr:  the author variables, a string containing anything else the 
     author wants to store to disk (this can be up to 255 characters).  A 
     null string ("") may be passed when no author variables need to be 
     stored.

     The Store command creates two files: 

     1)  A performance file, containing information on how well the student 
     did in the most recent session and on all sessions combined.  This file 
     lists in a short report format the number of questions answered, the 
     number correct, and the percentage as well as the amount of time spent 
     in the drill.

     2)  A state file, containing all the necessary information to allow the 
     state to be restored (see Restore) to the point at which it was saved.

     All files relating to a certain drill (specified by the drill ID) will be 
contained in a folder called DRLstr.DD (i.e. the drill ID is the filename with 
the extension .DD, for "drill data", appended to it).  The Store command looks 
for this folder using the path name specified by the PathName parameter (see 
Drill Author's Responsibilities).  If this folder does not exist, Store will 
create it.
     Inside the drill data folder, Store will create the performance file, 
entitled STUstr.PER (the student ID that is passed, appended with ".PER").  
Store also looks inside the drill data folder for the states folder (and 
creates it if necessary), named DRLstr.ST (the drill ID with the extension .ST 
for "states").  In this folder, Store creates the state file (STUstr.STA, the 
passed student ID with ".STA" appended).

     There may be several student performance files inside a single DrillData 
folder, each of these students having taken the same drill.  Each student 
would also have a corresponding state file inside the States folder (see 
Appendix B).
                                   - 24 -

     Store writes over old files; therefore, if Student X is using Drill Y and 
Store is called, it will destroy any previous files generated by the same 
student using the same drill.  Usually this makes no difference; if Restore 
was used, the old data is retained in cumulative form.  However, authors 
should make duplicates of any stored files they wish to retain indefinitely.
     Both the performance and the state files are standard text files.  The 
state file should not be modified or an error could occur during the Restore 
command.
     Note that STUstr and DRLstr must be less than or equal to 8 
characters in length consisting of the characters A - Z, a - z, 0 - 9, -(dash), 
and _(underscore).
     The format of the author variables string is up to the author; it can 
be any string, but most likely would be a list of numbers that the author 
has concatenated together (to be parsed after a call to Restore).  Line breaks 
can be embedded in the author variables string by concatenating carriage 
return and linefeed characters, if desired (see the sample drills on the 
distribution diskette for examples of this).
     Note that since Store is an OpenScript keyword, StoreDrill (or a 
similar name) must be used in ToolBook (see section Installing Drill Designer, 
above).


Examples:
ToolBook:     get StoreDrill(DataPtr, "C:\", "ST32", "Drill1", "23 13 7 late")

              This command will store the drill in the root directory of C: 
              under the name Drill1 with a student ID of ST32.  The final 
              string is the author variables string, which can contain 
              anything and should have meaning to the drill author.

Authorware:   To store the drill as Chem101 with student ID 007, and 
              with an author variables string containing the date the 
              assignment was given, perhaps:

              Store(DataPtr, PathName, "007", "Chem101", "1/31/94")

C:            Store (DataPtr, PathName, "John_3", "R3", "");

              If no string of author variables is to be used from C, a null 
              string must be specified.

                                   - 25 - 

                                    Restore
Syntax:
ToolBook:       set DataPtr to RestoreDrill(DataPtr,PathName,STUstr,DRLstr)
Authorware      DataPtr := Restore(DataPtr,PathName,STUstr,DRLstr)
C:              YourStr = Restore (&DataPtr, PathName, STUstr, DRLstr);

     STUstr: the student ID (up to 8 characters) [def. = null string]
     DRLstr: the drill ID (up to 8 characters)       [null string]

     Restore takes the place of the CreateDrill call and restores the state 
of the previously stored drill specified by the student ID and drill ID.
     When using the C library (assumed in C syntax above), it returns the 
string containing the author variables that were stored with the Store call 
(this can be up to 255 characters).  This string must be converted back into 
whatever format the author's original information was in (often the string is 
treated as a list of numbers and is parsed accordingly).  Also, note that 
with the C library call, the address of DataPtr is passed and DataPtr is 
directly set during the restore.
     When using the DLL or UCD (the ToolBook and Authorware syntaxes above), 
Restore returns the new pointer value for DataPtr.  To retrieve the author 
variables stored with the last Store call, a separate call to 
GetAuthorVariables must be made (see that command).
     Restore uses the path specified by the PathName parameter.  There it 
looks for the DrillData folder named DRLstr.DD, inside which it looks for the 
DRLstr.ST (states) folder.  There it locates the file STUstr.STA and reads the 
information.
     C Notes: YourStr should be a char *, not an array.  Also, it is important 
that the address of DataPtr is passed (i.e., it must be preceded by the "&" 
character).
     Note that since Restore is an OpenScript keyword, RestoreDrill (or a 
similar name) must be used in ToolBook (see section Installing Drill 
Designer, above).

                                   - 26 -

                               GetAuthorVariables
Syntax:
ToolBook:       put pointerString(0,GetAuthorVariables(DataPtr)) into YourStr
Authorware:     YourStr := GetAuthorVariables(DataPtr)
C:              (not applicable, see Restore above)

     A call to GetAuthorVariables returns the author variables that were stored 
with the last call to Store.  Note that when using the C library, these author 
variables are returned with the call to Restore (see above).
     Note that from ToolBook an additional function must be used to
retrieve the actual string (pointerString, shown in the examples above),
since the DLL actually returns a pointer to a string, not the string itself.

                                   - 27 - 

                                    Insert
Syntax:
ToolBook:       get Insert(DataPtr,Qnum,INSlist,LSTchar)
Authorware:     Insert(DataPtr,Qnum,INSlist,LSTchar)
C:              Insert (DataPtr, Qnum, INSlist, LSTchar);

     Qnum: the question number to be inserted
     INSlist: the positions at which to insert the question
     LSTchar: Identifies list to insert into ("F"=future queue, "L"= long list) 
         [default = "F"]

     Insert allows the author to modify the future queue or the long list by 
inserting a question at the specified positions.  To make the insertions 
correctly, INSlist should be specified in ascending order (e.g., "2 4 8"); 
otherwise, as insertions are made, previous insertions will be "pushed 
forward" and end up in the wrong place.  Note that the insertions are made 
exactly where specified and no methods used in "Incorrect" are used; if the 
list isn't long enough, the insertions are made at the end.


Examples:
ToolBook:       To insert item 5 into the long list at positions 3, 6 and 9:

          get Insert(DataPtr, 5, "3 6 9", "L")

Authorware:     To insert item 15 into the future queue at positions 5 and 
                100 (note that if the future queue is less than 100 elements 
                long the insertion will be made at the end).  

          Insert(DataPtr, 15, "5 100", "F")

C:        Insert (DataPtr, 10, "9 6 3", 'F');

                The above example would insert item 10 into the Future Queue, 
                but the resulting positions would be 11, 7 and 3 (the earlier 
                insertions are pushed forward by the lower insertions).

                C note:  LSTchar is surrounded by 'single' quotes.

                                   - 28 -  

                                     Purge
Syntax:
ToolBook:       get Purge(DataPtr,PURlist,LSTchar)
Authorware:     Purge(DataPtr,PURlist,LSTchar)
C:              Purge (DataPtr, PURlist, LSTchar);

     PURlist:  The list of items to purge or the list of positions to 
         eliminate.  If the first character in the string is a "P", then
         the list will be treated as a list of positions.
     LSTchar:  The list to operate on ("F"= future queue, "L"= long list) 
         [default = "F"]

     Purge can be used in two ways.  If a normal list of integers is passed 
as PURlist, then Purge will delete those items completely from the list 
specified by LSTchar.  Those items will no longer be present in the list; no 
data associated with them (times answered, times missed) is retained, and the 
items will not be placed in the retired items list.
     If a list of integers preceded by a "P" (P is the first character in the 
string) is passed, then Purge will delete the contents of those positions in 
the list.

Examples:
ToolBook:       Starting with a future queue = 
                2,4,6,8,10,12,14,16,18,20:

           get Purge(DataPtr, "P 3 6 9", "F")

                The resultant future queue will be:
                2,4,8,10,14,16,20 (positions 3,6 and 9 gone).

Authorware:     
          Purge(DataPtr, "12 10", "L")

                This will delete all occurrences of items 10 and 12
                from the long list (the order of the items is not
                important here, but when deleting positions it is).  

C:              
          Purge (DataPtr, "P1 2 3 4 5", 'F');

          Deletes the first five future queue positions.

          C note: LSTchar is surrounded by 'single' quotes.
                                   - 29 -

                                   Requeue
Syntax:
ToolBook:       get Requeue(DataPtr,Qnum,REQlist,LSTchar)
Authorware:     Requeue(DataPtr,Qnum,REQlist,LSTchar)
C:              Requeue (DataPtr, Qnum, REQlist, LSTchar);

     Qnum:  the question number to requeue
     REQlist:  the positions at which to re-insert the question
     LSTchar:  The list to be operated on ("L" = long list, "F" = future 
         queue)  [def.= "F"]

     Requeue removes an item from a list and re-inserts it into that list at 
specified positions.  Requeue can be thought of as a combination of Purge and 
Insert; it first purges an item from the list, then inserts it.  In fact, 
Requeue will act exactly like Insert if the item specified is not in the list 
already.  Requeue cannot be used to purge items, however; if it is unable to 
perform the insertions due to an invalid list, it will not perform the 
deletion.
     Performing a Requeue does not change any of the data associated with an 
item, such as times missed and times answered.


Examples:
ToolBook:       To remove item 10 from the future queue and re-insert it at 
                positions 2,4,6 and 8:

         get Requeue(DataPtr, 10, "2 4 6 8", "F")

Authorware:     
         Requeue(DataPtr, 333, "5 10", "L")

                This operation will insert item 333 into the long list at 
                positions 5 and 10, even if the item is not initially in the 
                "question pool size" range (this will generate a warning in 
                the next error message).  

C:              To make sure item 5 exists in the long list only at position 7:

         Requeue (DataPtr, 5, "7", 'L');

                C note: LSTchar is surrounded by 'single' quotes.

                                   - 30 - 

                                    Retire
Syntax:
ToolBook:       get Retire(DataPtr,Qnum)
Authorware:     Retire(DataPtr,Qnum)
C:              Retire (DataPtr, Qnum);

     Qnum:  The question number to retire

     Retire removes all occurrences of an item from the future queue, then 
retires the item either by adding it to the retired items list, or if it 
already exists there, by updating the data associated with the item in the 
retired items list. 
     If the item is not present in the future queue, the Retire call does 
nothing.
     Note that the Retire operation works only on the future queue; an item 
cannot be retired from the long list.

Examples:
ToolBook:       To retire item 10:

     get Retire(DataPtr, 10)

Authorware:     Begin with retired items list = 1,2,3,4,5
                and future queue = 3,7,10,4,7,8.

     Retire(DataPtr, 7)

                This results in a retired items list of 1,2,3,4,5,7
                and a future queue of 3,10,4,8.

C:              Assume question 5 is in both the retired items list and 
                the future queue.

     Retire (DataPtr, 5);

                This removes question 5 from the future queue; it remains 
                in the same place in the retired items list, with its 
                performance data updated.

                                   - 31 -  

                                     Pad
Syntax:
ToolBook:       get Pad(DataPtr, PADlist, LSTchar)
Authorware:     Pad(DataPtr, PADlist, LSTchar)
C:              Pad (DataPtr, PADlist, LSTchar);

     PADlist:  The list of items to pad.
     LSTchar:  The target of the pad operation ("F" = future queue, "L" = 
         long list) [def.= "F"]

     Pad adds the items in PADlist to the end of the list designated by 
LSTchar.  If an item in PADlist is non-existent, i.e., the item number is 
larger than the question pool size specified in CreateDrill, Pad will still 
add the item but a warning will appear in the next call to GetErrorMessage 
(see Appendix A).
     Pad preserves the order of the items as they are passed to it.  The 
rest of the list is unaffected by the addition of the new items.  
Performance data (times missed, times answered) stored with each item is 
kept consistent in cases where an item Padded to the end already exists 
in the list.

Examples:
ToolBook:       To add items 2, 4 and 6 to the end of the future queue:

     get Pad(DataPtr, "2 4 6", "F")

Authorware:     To add items 2, 4 and 6 to the end of the long list:

     Pad(DataPtr, "2 4 6", "L")

C:              To add items 16, 3, 6 and 2 to the end of the future queue:

     Pad (DataPtr, "16 3 6 2", 'F');

                C note: LSTchar is surrounded by 'single' quotes. 

                                   - 32 -

                                  RetrieveInfo
Syntax:
ToolBook:       set YourNum to RetrieveInfo(DataPtr,INFOnum,EXP1,EXP2)
Authorware:     YourNum := RetrieveInfo(DataPtr,INFOnum,EXP1,EXP2)
C:              YourNum = RetrieveInfo (DataPtr, INFOnum,EXP1,EXP2);
                /*   In C, YourNum should be of type long    */

     INFOnum:  An integer specifying the information requested.
     EXP1, EXP2:  Extra parameters to be passed, as follows.

Variable parameters:  Depending on the value of INFOnum, additional 
parameters will be necessary as follows:
     INFOnum                         extra parameters
     1-3, 10-15, 19-20               (none)
     4-9                             Qnum
     16-18, 22                       Pnum
     21                              HLLnum, FRMchar

     Qnum:  Specifies the item number for these requests.
     Pnum:  Specifies the list position for these requests.
     HLLnum:  Specifies how long the hardest items list is to be.
     FRMchar:  Determines how the hardest items list is to be 
         constructed.                    [default = #]

     RetrieveInfo returns information requested by the author.  The first 
number passed (INFOnum) indicates the information returned, as follows:
     1) The length of the future queue is returned.
     2) The length of the long list is returned.
     3) The length of the retired items list is returned.
     4) Returns the number of times an item (specified by Qnum) is in the 
        future queue.
     5) Returns the number of times an item (Qnum) is in the long list.
     6) Returns the number of times an item (Qnum) is in the retired items 
        list (this is either 0 or 1).
     7) Returns the number of times an item (Qnum) has been missed.
     8) Returns the number of times an item (Qnum) has been given.
     9) Returns the percentage of times an item (Qnum) has been 
        missed (rounds to nearest integer).
    10) Returns the number of questions the user has answered for all 
        sessions of the drill.
    11) Returns the number of questions the user has answered for the 
        current session only.
                                   - 33 -

    12) Returns the number of questions the user has answered correctly 
        for all sessions of the drill.
    13) Returns the number of questions the user has answered correctly 
        for the current session only.
    14) Returns the percentage of questions that the user has answered 
        correctly for all sessions of the drill.
    15) Returns the percentage of questions that the user has answered 
        correctly for the current session only.
    16) Returns the item in position Pnum of the future queue.
    17) Returns the item in position Pnum of the long list.
    18) Returns the item in position Pnum of the retired items list.
    19) Returns the time (in seconds) that the user has spent in the drill for 
        all sessions.  In C, this result should not be stored in a short 
        integer as it may be too large.
    20) Returns the time (in seconds) that the user has spent in the drill for 
        the current session.  In C, this result should not be stored in a 
        short integer as it may be too large.
    21) This option constructs a list of the hardest questions.  The length 
        of the list is specified by HLLnum.  The format (method of 
        construction) is specified by FRMchar; this can be either "#", 
        which means the list is constructed by the number of times the 
        question is missed, or "%", which signifies that the list is 
        constructed based on percentage of times missed.  In both 
        cases, ties are referred to the other method; i.e., if "%" is used 
        and two questions have been missed every time, one missed 10 
        out of 10 times will be listed before one missed 5 out of 5 times.  
        If a question has not been missed, it will not be put into the 
        hardest items list.  Thus the resultant list will not contain HLLnum 
        items if fewer questions have been missed; the returned value 
        equals the length of the list that was constructed by the call.
    22) Returns the item in position Pnum of the hardest items list.  It will 
        return 0 if the position doesn't exist or the hardest items list has 
        not been created.  Usually, a call is made to 21 immediately 
        before this one to ensure that the list is correct; if calls have 
        been made to Correct, Incorrect, Purge, etc. since the last call 
        to 21 the hardest items list may no longer be up-to-date.

Examples:
ToolBook:               
         set YourNum to RetrieveInfo(DataPtr, 1, 0, 0)

              YourNum now contains the length of the future queue.
                                   - 34 -

         set YourNum to RetrieveInfo(DataPtr, 17, 5, 0)

              YourNum now contains the 5th item in the long list.

         set YourNum  to RetrieveInfo(DataPtr, 21, 10, "#")

              This constructs a list of the items that have
              been missed the most (length = YourNum, which is
              10 or less).  

Authorware:
         YourNum := RetrieveInfo(DataPtr, 21, 15, "%")

              Constructs a list of the items that have been
              missed the highest percentage of times (the length
              of the list is 15 or less).  
              
         YourNum := RetrieveInfo(DataPtr, 22, 5, 0)

              YourNum now contains the 5th item in the hardest        
              items list.

C:              
         YourNum = RetrieveInfo (DataPtr, 8, 5);

              YourNum now contains the number of times that           
              question five has been answered.

         YourNum = RetrieveInfo (DataPtr, 12);

              YourNum now contains the total number of
              questions the user has answered correctly for all
              sessions of the drill.  

              C note:  EXP1 and EXP2 do not need to be passed
              to the lib unless required by the call.  Be sure to use
              'single' quotes to surround FRMchar (e.g., '%').

                                   - 35 -

                           Appendix A: Error Messages

     The following is an alphabetical list and explanation of all error 
messages that Drill Designer can return to GetErrorMessage.  The text 
explains which calls can yield these results, whether the command was 
executed (or continued from the point of error), and lists situations that 
may have caused the error itself.

     Message:                                Occurs in:              Executed?
Author variables list shortened              Store                   Yes
     Explanation:  The string that contains the additional information that 
     the author wants stored in the state file cannot be greater than 255 
     characters, or it will be truncated.

     Message:                                Occurs in:               Executed?
Can't open state file                        Restore                  No
     Explanation:  Restore attempted to read from a state file that doesn't 
     exist; the name may have been incorrectly specified, the file might not 
     be in the path specified by PathName, or it could be a disk error.  

     Message:                                Occurs in:               Executed?
Can't write performance file                 Store                    ???
     Explanation:  During a Store, the performance file could not be created.  
     This may be due to a disk error or a lack of disk storage space.  The 
     state file might still be successfully written, however.

     Message:                                Occurs in:               Executed?
Can't write state file                       Store                    ???
     Explanation:  During a Store, the state file could not be created.  This 
     may be due to a disk error or a lack of disk storage space.  The 
     performance file might have been successfully written, however.

     Message:                                Occurs in:               Executed?
Drill and/or student id invalid              Restore, Store           No
     Explanation:  The drill or student id passed to Store or Restore is invalid. 
     These must be less than or equal to 8 characters in length and consist of
     the letters A - Z, a - z, 0 - 9, -(dash), or _(underscore).  No spaces are
     allowed.  The requested store or restore was aborted because of this.

     Message:                                Occurs in:               Executed?
Drill data directory cannot be opened        Restore, Store           Yes
     Explanation:  The Drill data directory was not found at the PathName 
     specified and could not be created (if it did not exist). 
 
     Message:                                Occurs in:               Executed?
Drill ID too long                            Store, Restore           Yes
     Explanation:  The string passed as the drill ID (DRLstr) can be no longer 
     than 8 characters; if it is longer, it is truncated.
                                   - 36 -

     Message:                                Occurs in:               Executed?
Fewest insertions invalid, set to 1          CreateDrill              Yes
     Explanation:  The fewest insertions (passed as FEWnum when using the 
     "RDII" and "RDIns" insertion techniques) cannot be less than zero nor 
     greater than the number of insertions passed in INClist  (the insert 
     positions for Incorrect calls).

     Message:                                Occurs in:               Executed?
Future Queue empty                           Correct, Incorrect       No
     Explanation:  Correct and Incorrect cannot function if the future queue is 
     empty, since there is no first item to specify as correct or incorrect.

     Message:                                 Occurs in:              Executed?
Hardest Items List form invalid, default set  RetrieveInfo(21)        Yes
     Explanation:  The character passed to specify the format of the hardest 
     items list must be a "#" or a "%" character.  The default is "#".

     Message:                                Occurs in:               Executed?
Hardest Items List position invalid          RetrieveInfo(22)         Yes
     Explanation:  The position specified does not exist for the hardest items 
     list.  Either the position was not a positive value or it was greater than 
     the length of the hardest items list.  A zero is returned by the function 
     in this case.

     Message:                                  Occurs in:             Executed?
Hardest Items List size invalid, default set   RetrieveInfo(21)       Yes
     Explanation:  The length specified for the hardest items list is either 
     less than one or greater than the maximum integer size allowed.  The 
     default is 1.

     Message:                                  Occurs in:             Executed?
Insert technique string invalid, set to RFII   CreateDrill            Yes
     Explanation:  The string that contains the insertion technique to be used 
     could not be identified as one of the valid options.

     Message:                                  Occurs in:             Executed?
Invalid pathname: default taken                Store, Restore         Yes
     Explanation:  The PathName (see Drill Author's Responsibilities) was not 
     found; the default PathName ("") was used.  The DrillData folder is placed 
     in the currently active directory and path.
                                                
     Message:                 Occurs in:                              Executed?
Invalid item number           Retire,Insert,Requeue,RetrieveInfo      No
     Explanation:  The item number specified is either less than 1 or is 
     greater than the maximum allowed integer size.

     Message:                               Occurs in:                Executed?
Invalid target list char, default set       Requeue,Purge,Insert,Pad  Yes
     Explanation:  The character that specifies the list to perform these 
     operations on must be specified with an "F" or an "L" ("F" is the default).
                                   - 37 -

     Message:                                Occurs in:               Executed?
Item larger than question pool size          Requeue, Insert, Pad     Yes
     Explanation:  The item specified to use in these actions is larger than 
     the initial size of the long list; this means the item does not exist in 
     the "question pool" as defined in CreateDrill, thus this warning is 
     issued.

     Message:                                Occurs in:               Executed?
Item not in queue                            Retire                   No
     Explanation:  The item to be retired was not present in the future queue 
     and thus cannot be retired.

     Message:                Occurs in:                               Executed?
List unusable for []         CreateDrill,Requeue,Purge,Insert,Pad     ???
     Explanation:  A string that contains a list yielded unusable data.  For 
     the latter four commands above, the message contains the routine name at 
     the end, and the command is not executed.  For CreateDrill, the name of 
     the unusable list (either "Incorrect" or "Replenish") follows, but the 
     CreateDrill command is executed.  An unusable list results from a null 
     string ("") being passed, or any string that contains no numbers, such 
     as "this is an invalid list string."

     Message:                                Occurs in:               Executed?
No insert positions list, can't execute      Requeue, Insert          No
     Explanation:  The insert positions list was invalid; Insert will not make 
     any insertions, and Requeue will neither make insertions nor remove the 
     item from the specified list in the first place (this prevents Requeue 
     from purging an item accidentally).
                                        
     Message:                           Occurs in:                    Executed?
# of questions invalid, default set     CreateDrill                   Yes
     Explanation:  The number of questions (FQnum) was either less than zero or 
     greater than the maximum allowed integer.  The default value is 20, unless 
     the question pool size (QPnum) is less than 20, in which case QPnum is 
     used.

     Message:                            Occurs in:                   Executed?
# of repeats invalid, default set        CreateDrill                  Yes
     Explanation:  The number of repeats (REPnum) specified must be greater 
     than zero (remember, this specifies how many times the future queue is 
     presented) and less than the maximum allowable integer.

     Message:                            Occurs in:                   Executed?
Number to retire invalid, set to 1       CreateDrill                  Yes
     Explanation:  The number to retire before replenishing (RPLnum), a 
     variable parameter used with the "EC" insertion technique, must be greater 
     than zero but cannot be greater than FQnum.  

     Message:                            Occurs in:                   Executed?
Orientation invalid, set to S            CreateDrill                  Yes 
     Explanation:  The character (ORDchar) that determines whether the long 
     list is to be sequential ("S") or random ("R") did not contain a valid 
     character.
                                   - 38 -

     Message:                            Occurs in:                   Executed?
Out of source elements                   Incorrect                    Yes
     Explanation:  This message may occur when Incorrect is using Resurrection 
     or Appending methods to lengthen the future queue.  For Resurrection, if 
     the retired items list is empty, and for Appending, if the future queue is 
     empty, this message will appear.

     Message:                            Occurs in:                   Executed?
Purge position doesn't exist             Purge                        No
     Explanation:  The purge position specified is greater than the length of 
     the list specified.  

     Message:                                Occurs in:               Executed?
Question pool size reset to # of questions   CreateDrill              Yes
     Explanation:  The question pool size cannot be less than the number of 
     questions in the initial future queue, nor can it be greater than the 
     maximum allowed integer.  If the number of questions (FQnum) is also 
     invalid, both are set to 20.

     Message:                Occurs in:                               Executed?
Ran out of memory            CreateDrill,Correct,Incorrect,Requeue,   varies
                             Retire,Insert,Pad,Correct,Purge 
     Explanation:  At some point in the routine, there was not sufficient 
     memory to allocate memory for an item.  The command may have been 
     partially completed (in CreateDrill, this may occur if allocating a huge 
     long list and future queue) or not at all.  In any case, this error 
     generally signifies that the queues are too large for the memory 
     available on your system.  Note that depending on the circumstances, there 
     may not even be enough memory available to retrieve this message, nor 
     execute any other command, so try to avoid running out of memory.

     Message:                                Occurs in:               Executed?
Request not within valid parameters          RetrieveInfo             No
     Explanation:  The integer that specifies the information requested must 
     be greater than zero but not greater than the highest numbered request 
     (22 as of this version).

     Message:                                Occurs in:               Executed?
Smallest position invalid, set to 1          CreateDrill              Yes
     Explanation:  The smallest position (SMLnum) specified when using "DII", 
     "RDII", and "RDInt" insertion techniques cannot be less than one, nor can 
     it be greater than any of the positions specified in the incorrect 
     positions list.

     Message:                                Occurs in:               Executed?
States file directory cannot be opened       Restore, Store           Yes
     Explanation:  The States folder was not found at the PathName specified   
     and could not be created (if it did not exist).
 
     Message:                                Occurs in:               Executed?
Student ID too long                          Store, Restore           Yes
     Explanation:  The string passed as the student ID (STUstr) can be no 
     longer than 8 characters; if it is longer, it is truncated.

                                   - 39 -

                     Appendix B: Store and Restore File Map
     ______
     |____|__________
     |              |\    _______________________________________
     |  Drill Data  | \   |  _____         _____                | 
     |  directory   |  \  |  |   |         |   |     . . .      |
     |______________|   \ |  |___|         |___|                |
       Drill_ID.DD       \| Stud_ID1.PER  Stud_ID2.PER          |
                          |  _____                              |
                          |  |___|______________                |
                          |  |                 |                |
                          |  |  States         |                |
                          |  |  directory      |                |
                          |  |                 |                |
                          |  |_________________|                |
                          |     Drill_ID.ST  \                  |
                          |___________________\_________________|
                                               \
                              __________________\________________________
                              |                                         |
    The Drill data directory  |       _____        _____                |
    is contained in the last  |       |   |        |   |      . . .     |
    directory in the path     |       |___|        |___|                |
    specified in the PathName.|    Stud_ID1.STA  Stud_ID2.STA           |
                              |                                         |
                              |                                         |
                              |                                         |
                              |_________________________________________|


