drill designer web service - ddra.its.uiowa.edus... · drill designer web service user/developer...

Copyright © 1991 – 2007 The University of Iowa 1

Drill Designer Web Service USER/DEVELOPER DOCUMENTATION August 2007 Version 1.0

Credit for the instructional design theory upon which Drill Designer is based goes to Stephen Alessi and Stanley Trollip (refer to Multimedia for Learning: Methods and Development, Third Edition, Allyn and Bacon, 2001)


Table of Contents

Getting Started With Drill Designer ............................................................... 3

The Purpose of Drill Designer ......................................................................................... 3 Requirements for Using Drill Designer ........................................................................... 3 Drill Designer Overview ................................................................................................. 4 Simple Drill Program Flow ............................................................................................. 5 Notes on Parameter Formats ........................................................................................... 6

Simple Drill Commands ................................................................................. 7

ddCreateDrill ................................................................................................................... 8 ddDispose ...................................................................................................................... 12 ddGetErrorMessage ....................................................................................................... 13 ddNext ........................................................................................................................... 14 ddCorrect ....................................................................................................................... 15 ddIncorrect ..................................................................................................................... 16

Commands for Retaining & Obtaining Student Performance Information .. 18

ddStore ........................................................................................................................... 19 ddRestore ....................................................................................................................... 20 ddIsStudentTakingDrill ................................................................................................. 21 ddSetDeveloperVariables .............................................................................................. 22 ddGetDeveloperVariables ............................................................................................. 23 ddRetrieveInfo ............................................................................................................... 24 ddRetrieveQueue ........................................................................................................... 26 ddGenerateHardestItemsList ......................................................................................... 27 ddGetHardestItemAt ...................................................................................................... 28

Drill Modification Commands ...................................................................... 29

ddInsert .......................................................................................................................... 30 ddPurge .......................................................................................................................... 31 ddRequeue ..................................................................................................................... 32 ddRetire ......................................................................................................................... 33 ddPad ............................................................................................................................. 34 ddScramble .................................................................................................................... 35

Appendix: Error Codes and Error Messages ............................................... 36

Error Codes .................................................................................................................... 36 Error Messages .............................................................................................................. 37


Getting Started With Drill Designer This section contains information that will help developers get started with Drill Designer, explaining its purpose, the requirements for using it, the basic concepts involved, and some details on calling syntaxes. It is suggested that developers read at least this section and the next one, entitled “Simple Drill Commands,” before attempting to produce an application with Drill Designer. The Purpose of Drill Designer Drill Designer is a tool intended to facilitate data manipulation and storage for educational web sites which provide repeated practice of material to be learned. In such practice, such as learning the vocabulary of a foreign language, much repetition is necessary. When students make mistakes during practice, that material needs to be practiced more and sooner. In contrast, when students perform correctly, that material needs to be practiced less and not as soon. Although this basic concept is simple (repeat sooner after errors, less soon after correct performances), its implementation in software can become very complicated and tedious, especially if you must keep track of a large amount of practice material (e.g., the thousands of words of a new language). Drill Designer keeps track of correct and incorrect performances and maintains a queue of items. In essence it “recommends” what should be practiced at any point in time, based on past correct and incorrect actions. In addition, in any discipline with a lot of material, students cannot master all content in a single session at a computer. Drill Designer maintains a permanent database of individual students and lessons so that students can work a little at a time (thus maintaining attention and motivation) over days, weeks, or months. Requirements for Using Drill Designer Drill Designer is provided as a web service accessible through the Simple Object Access Protocol (SOAP). If you do not know what a web service is, and haven’t heard of SOAP, we recommend a basic search on these topics using your web browser and your favorite internet search engine. We won’t cover these topics here.

Any web application development tool that supports SOAP can call Drill Designer routines. This includes the vast majority of languages and tools (Flash, PHP, .NET languages, JAVA, JavaScript, etc.). Developers should have a good working knowledge of the programming languages and tools they will use.

Drill Developers must have a developer ID (identifier), which can be obtained through a web form at the Drill Designer Information and Registration website at:

http://ddra.its.uiowa.edu

Along with their ID, developers will receive information specifying the precise URL to use when connecting to the web service. Developers should also spend time looking around the registration website, as it contains further information they will find useful—running demos, downloadable source samples, and supplemental documentation for using Drill Designer with specific languages.

In order to use Drill Designer effectively, developers must also have an understanding of the concepts employed in Drill Designer and detailed knowledge of how the routines operate. This document provides only an overview of the former, but detailed information on the latter. Developers wanting more background on the concepts may wish to consult the “Drills” chapter of the following book.

Alessi, Stephen and Trollip, Stanley, Multimedia for Learning: Methods and Development. 3rd ed. Allyn and Bacon, 2001.


Drill Designer Overview

Drill Designer provides a set of routines enabling advanced queuing and data storage/retrieval mechanisms for web-based drills. Specifically, Drill Designer handles the creation of a list of items and the subsequent modification of that list based on correct or incorrect responses from a drill-taker. Drill Designer simplifies drill programming and adds features that can automatically provide extra help, on items missed most often, thereby increasing the effectiveness of the drill.

In Drill Designer, the list of items yet to be given is referred to as the “future queue.” Note that this queue does not contain the actual content of the items, but simply item numbers that the drill developer uses as an index to the actual content. The content of items may be on web pages, in Flash frames, in records of a database, etc.

The future queue is created from another list referred to as the “long list.” The long list contains numbers for all the items that can be presented in the drill. You may have 500 drill items to give, for example, but deliver only 50 at a time. In this case, the future queue would initially hold 50 unique numbers for items to deliver next, and the long list would hold 450 unique numbers for items to give later. Additional items can then be drawn from the long list as desired.

The next item to deliver always comes from the front of the future queue. If the user answers the item correctly, Drill Designer makes note of that and the item is removed from the front of the queue. If that was the last occurrence of that item in the future queue, the item is considered mastered by the drill-taker and is added to the “retired items list.”

When the user answers an item incorrectly, Drill Designer records that and then employs a technique known as variable interval performance queuing (or VIP queuing). With VIP queuing, all occurrences of the missed item are first removed from the future queue. Then, the item is reinserted back into the future queue at multiple positions of increasing interval, selected by the drill-developer, such that the drill-taker will be presented the item again soon—while it’s in short-term memory (also called working memory)—then at increasing intervals pushing beyond the short-term memory boundary. In this way the user is assisted in committing the item to long-term (more permanent) memory.

As the future queue becomes smaller, it may not be long enough to allow reinsertion of missed items 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 developer. Insertion techniques are described in depth under the ddIncorrect command. More information on these techniques and their underlying learning theory can be found in Alessi, S. M., & Trollip, S. R. (2001), Multimedia for Learning: Methods and Development.

Also note that Drill Designer prevents situations where instances of the same item number end up side-by-side in the future queue. It will separate items if possible or remove the extras.


Simple Drill Program Flow The commands ddCreateDrill, ddNext, ddCorrect, ddIncorrect and ddDispose form the core of Drill Designer. ddGetErrorMessage is also frequently used when developing a new drill. With these six commands a developer can create and process single-session drills with much flexibility. (Multi-session drills would incorporate additional commands, such as ddIsStudentTakingDrill, ddRestore and ddStore). Below, the basic flow of a single-session drill is described. • ddCreateDrill 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 developer specifies many parameters used in the creation and upkeep of the drill.

• ddGetErrorMessage is used often while testing a drill application during its development. A call to ddGetErrorMessage returns a string containing any error messages and warnings resulting from the previous call (e.g., ddCreateDrill in this example). When the drill has been thoroughly tested, the developer can remove calls to ddGetErrorMessage.

Then, the flow becomes a loop:

• ddNext returns the item number indicating the item to be given next. The developer uses this number as an index to the actual item content, presenting it to the user and allowing a response. Note: when ddNext returns 0, there are no more items left in the queue and the drill has been completed.

Depending upon whether the user responds correctly or incorrectly, the developer calls either:

• ddCorrect, which triggers all queue actions for a correct response, including removing the item from the front of the future queue, thereby readying the next item to be retrieved by ddNext.

• ddIncorrect, which triggers all queue actions for an incorrect response, including removing the item completely from the queue and reinserting it at the “insert positions” specified in the ddCreateDrill call. Again, the subsequent call to ddNext will provide the next item number to be used.

• ddDispose frees the memory used by Drill Designer. When the drill is complete (i.e., ddNext returns

0), or the user wants to quit, etc. the program should execute a ddDispose.


Notes on Parameter Formats Each description of a Drill Designer routine in this document first contains a description of the routine’s calling syntax. Where parameters are necessary, a type and mnemonic descriptor are shown for each parameter, as well as default values, if there are any. Conventions of the C# language are used for all examples in this document. Supplementary documents describing parameter passage and syntax for specific languages (e.g., Flash, JavaScript) are available at the Drill Designer Information and Registration website.

Parameter Types int: an integer (number) or a variable containing an integer String: a string or a variable containing a string. String parameters are surrounded by double

quotes ("this is a string") boolean: A value that can be “true” or “false” type[ ]: Brackets following a type indicate a list or array of the variable type. For example,

“new int[] {3, 6, 9, 12}” and “new int {17}” both create arrays of integers, the latter being an array of only one element.

Enumerations: C# enumerations define some additional parameter types in the Drill Designer

web service (e.g., InsertionTechnique, below) consisting of a set of named constants (e.g., DII, RDII, …), having the underlying type of int, where the first enumerator (e.g., DII) has the value 0 and each successive enumerator increases by 1. The enumerations are defined to add meaning to parameters that indicate selected options, in that mnemonic string values (DII) can be passed instead of integer values (0) as selectors. Any language that does not handle enumerations must pass the enumeration as an actual string (e.g., “DII”). (Note: examples of calling syntax for specific languages other than C#, such as Flash or JavaScript, are contained in supplemental documents available at the information and registration website.)

The following enumeration types are defined in the Drill Designer web service: InsertionTechnique = DII, RDII, RDIns, RDInt, RFII, EC ListType = ITEMS, POSITIONS ListFormat = NUMBER, PERCENTAGE QueueType = RI, FQ, LL InfoIdType = FQ_LENGTH, LL_LENGTH, RI_LENGTH, FQ_TIMES_PRESENT, LL_TIMES_PRESENT, RI_TIMES_PRESENT, TIMES_MISSED, TIMES_GIVEN, PERCENT_MISSED, QUESTIONS_TOTAL, QUESTIONS_CURRENT_SESSION, CORRECT_TOTAL, CORRECT_CURRENT_SESSION, PERCENT_CORRECT_TOTAL PERCENT_CORRECT_CURRENT_SESSION FQ_ITEM_AT, LL_ITEM_AT, RI_ITEM_AT, TIME_TOTAL, TIME_CURRENT_SESSION, HARDEST_ITEMS, HARDEST_ITEM_AT


Simple Drill Commands As mentioned earlier in the description of a simple drill program flow, there are six commands that can be used to form simple, single-session drills:

ddCreateDrill ddGetErrorMessage ddNext ddCorrect ddIncorrect ddDispose

These commands form the core of Drill Designer and will be used in virtually every drill you make. They are described in this section.


ddCreateDrill

C# Syntax: int ddCreateDrill (

String developerId, String drillId, String studentId, int numFutureQueueItems, int numRepeat, int questionPoolSize, boolean randomize, InsertionTechnique insertionTechnique, int[] insertPositions, int smallestInsertPos, int fewestNumInsert, int numRetiresToReplenish, int[] replenishPositions )

Parameters: PARAMETER

DESCRIPTION DEFAULT VALUE

developerId The secret developer ID given to each developer during registration.

drillId The drill name (e.g., “geog1”) uniquely identifying the drill from other drills by the developer.

studentId The ID associated with the student taking the drill. The ID must be unique to a student within the drill to prevent collisions with simultaneous users and should be as unchanging as possible if the drill will be stored and restored at a later date. The literal string “$Unique$” may be passed to have a unique student ID generated by Drill Designer.

numFutureQueueItems The number of different items to be in the future queue initially.

questionPoolSize (if specified and valid) or 20

numRepeat The number of times to present the initial future queue (the queue is repeated numRepeat times).

1

questionPoolSize The total number of items in the drill. This should be greater than or equal to numFutureQueueItems. Developers must take care that questionPoolSize is as large as their largest drill item number.

numFutureQueueItems (if specified and valid) or 20

randomize Determines the order (orientation) of the future queue and long list: false (sequential) or true (random).

false


Parameters (continued, for ddCreateDrill…): insertionTechnique The insertion technique used for calls to

ddIncorrect. Choices are (use the enumeration corresponding to the method): DII (Diminishing Insertions and Intervals) RDII (Resurrection with Diminishing Insertions

and Intervals) RDIns (Resurrection with Diminishing Insertions) RDInt (Resurrection with Diminishing Intervals) RFII (Resurrection with Fixed Insertions and

Intervals) EC (Endless Continuum)

RFII

insertPositions[] The list of the insert positions used for calls to ddIncorrect.

3, 8, 17

smallestInsertPos Smallest insertion position allowed. Note: required for insertion techniques DII, RDII, and RDInt. If other insertion technique is specified, just pass 0 for this parameter.

1

fewestNumInsert Fewest number of insertions allowed. Note: required for insertion techniques RDIns and RDII. If other insertion technique is specified, just pass 0 for this parameter.

1

numRetiresToReplenish Number of items to retire before replenishing. Note: required for insertion technique EC. If other insertion technique is specified, just pass 0 for this parameter.

1

replenishPositions[] List of positions to use when replenishing. Note: required for insertion technique EC. If other insertion technique is specified, just pass null for this parameter.

1, 3, 5

Returns: The session ID to be used for subsequent Drill Designer calls made in the same session. An error code may be returned instead of the session ID (see Appendix).

Description: ddCreateDrill creates and initializes a new drill. It sets up the initial future queue, long list and other structures and settings according to parameters passed. Note: as a convenience for developers when a unique student ID is not obtainable, a studentId of “$Unique$” may be passed, causing Drill Designer to internally generate and maintain a unique student ID associated with the returned session ID. Up to 100 such sessions are allowed per developer, per drill. (This limit is not in place when regular student IDs are supplied by the developer.) Be careful to note that this mechanism can be used only with single-session drills. For multi-session drills involving ddStore and ddRestore, it is essential that students know and are familiar with their student ID. A call to ddStore passing a session created with the “$Unique$” mechanism will generate an error. ddCreateDrill or ddRestore must be called before other Drill Designer commands can take place. If neither ddCreateDrill nor ddRestore has been called, the user session, referenced by the returned sessionId, will not be available and the other routines, which require sessionId, cannot be called (will return an invalid sessionID error code). When finished with a drill, ddDispose should be called to clear the


session memory. In order to find out whether a student has already started with a particular drill (in which case ddRestore should be called instead of ddCreateDrill), use the ddIsStudentTakingDrill call. ddCreateDrill first builds the long list using questionPoolSize for the length. If randomize is “true,” the list is randomized. Otherwise, the list is in sequential order. Either way, the long list contains the same numbers, but in a known, sequential order, or an unknown, random order. The future queue is then constructed by pulling numFutureQueueItems items from the front of the long list. These items are removed from the long list, leaving it shorter (and often empty—frequently numFutureQueueItems is equal to questionPoolSize). Note that, while not common practice, numFutureQueueItems can also be 0 (zero), which might be useful if a developer wants to build a future queue completely from scratch using the drill modification commands (see the Drill Modification Commands section). The future queue is then repeated based on numRepeat. A value of 1 means the future queue is left as it is; 2 means it is doubled (i.e., repeated once), and so on. Thus numRepeat specifies the number of times each item exists in the future queue at the start of the drill. It’s worth noting that, if randomize was “true,” repeated instances of the future queue are themselves internally randomized, so that the "randomness" is not compromised through a repeated pattern. Drill Designer has a built-in mechanism to ensure that two instances of the same item do not exist side-by-side in the future queue, as could occur where one grouping ends and the next grouping begins. insertionTechnique specifies the insertion technique to be used with items answered incorrectly (see ddIncorrect for more detailed information about how the insertion techniques work):

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) Endless Continuum (EC)

Based on this parameter, other parameters may be needed, as indicated in the descriptions for smallestInsertPos, fewestNumInsert, numRetiresToReplenish, and replenishPositions. 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 numFutureQueueItems and questionPoolSize are equivalent. It is possible, though, to perform many operations on the long list regardless of the insertion technique being used; a developer may want to start with a larger item pool while using DII, for example, and use the drill modification commands to have control over replenishing. It’s worth mentioning again that randomization (specifiec by the randomize parameter) occurs first in the long list. The future queue is then built from the long list. Therefore, if “true” is specified for randomize with questionPoolSize at 40 and numFutureQueueItems 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, questionPoolSize would have to be set to 20. The following diagram illustrates the sequence and affect on the long list and future queue, given the example call.


C# Example: sessionId = WebService.ddCreateDrill(developerId, uniqueDrillId, uniqueStudentId, 5, 3, 10,

true, InsertionTechnique.RFII, new int[] {4, 11}, 0, 0, 0, null);


ddDispose

C# Syntax: int ddDispose (int sessionId)



sessionId The session ID returned by ddCreateDrill or ddRestore.

Returns: A 0 (zero) if successful, or an error code (see Appendix).

Description: ddDispose frees the memory used by a Drill Designer (identified by sessionID). It does not delete the drill from the database, nor does it store unsaved data in the database. A call to ddStore needs to precede ddDispose if saving the drill data is desired before ending the session with ddDispose. It is good programming practice for developers to always call ddDispose to dispose of the session when a drill ends. If ddDispose is not called, the session will eventually timeout and be cleared from memory, but until then, memory is being wasted by an unused session.

C# Example: disposeState = WebService.ddDispose(sessionId);


ddGetErrorMessage

C# Syntax: String ddGetErrorMessage (int sessionId)




Returns: A string containing one or more error messages generated during the previous Drill Designer call, or an empty string indicating that no error occurred. Error messages are listed alphabetically in the Appendix.

Description: ddGetErrorMessage returns a string containing the error message(s) that were generated by the previous Drill Designer call. Some error messages indicate that the previous command could not be executed, while others are merely warnings signifying that, although the command was executed, certain parameters were not specified appropriately and defaults were used instead. ddGetErrorMessage is useful for the developer while creating a drill to ensure that all commands are recognized and that parameters are appropriate. Once the drill is executing correctly, calls to ddGetErrorMessage may be removed at the developer’s discretion. When there is no error or warning from the previous call, ddGetErrorMessage returns an empty string. Therefore, testing for a zero-length return string can be used as a flag. All error messages are listed in the Appendix, with further clarification of their meaning, and indication of whether the command executed. Important related note: All routines that return an integer type may return an error code instead of the expected return value. Error codes are negative numbers corresponding to particular error types. Some error codes (e.g., -1 [invalid sessionID]) indicate that Drill Designer cannot communicate with the drill session. Therefore, further information about the error cannot be obtained through a call to ddGetErrorMessage. For all other error codes (e.g., -2 [Error occurred]) a following call to ddGetErrorMessage will provide more detail. See the Appendix for an explanation of both error codes and error messages. ddGetErrorMessage itself does not generate error messages or change the last message generated by another call.

C# Example: errMsg = WebService.ddGetErrorMessage(sessionId);


ddNext

C# Syntax: int ddNext (int sessionId)




Returns: The integer value of the next item in the future queue (i.e., the next item to deliver in the drill), or an error code (see Appendix). If the future queue is empty, ddNext returns a zero.

Description: A call to ddNext returns the value of the next item in the future queue. The call does not change the future queue in any way (i.e., repeated calls to ddNext yield the same result). ddNext is used by the developer to determine the next drill item to present to the student.

C# Example: nextItem = WebService.ddNext(sessionId);


ddCorrect

C# Syntax: int ddCorrect (int sessionId)




Returns: The integer value of the next item in the future queue (i.e., the next item to deliver in the drill), or an error code (see Appendix). If the future queue is empty, ddCorrect returns a zero.

Description: The developer calls ddCorrect when the drill-taker correctly answers an item. Drill Designer adds 1 to the number of times the item has been presented and answered correctly. The item is then removed from the head of the future queue. When the item is removed, if there are no more occurrences of the item remaining in the future queue, the item is considered mastered and is retired. Specifically, it is placed into the retired items list. It is possible that the item already exists in the retired items list—it may have been retired earlier, but placed back in the future queue for numerous reasons. In this case, the item is not added again, nor is its position in the retired items list changed. The position of items in the retired items list is kept in the order of first-mastery, as an indication of item difficulty. When items are resurrected (brought back into the future queue from the retired items list—see ddIncorrect), they are drawn from those retired last—and therefore the more difficult items for that particular user. When the endless continuum ("EC") insertion technique is being used and the number of items to retire before replenishing (numRetiresToReplenish) has been reached, replenishing occurs. Replenishing removes a group of items the size of numRetiresToReplenish (e.g., 5) from the long list and then inserts the group of items into each of the future queue positions indicated in replenishPositions. The group is placed such that the entire group ends up at the respective replenish positions (when counting the group as though it were 1 item). For example, if five items are to be replenished into positions 3 and 6, then after the operation the items will exist at positions 3, 4, 5, 6 and 7 and 10, 11, 12, 13 and 14. Also note that each group of items is inserted in a unique random order if randomize was passed as true in the ddCreateDrill call. When replenishing is finished, the counter that triggers replenishing is reset to 0. Replenish will occur again the next time numRetiresToReplenish is reached.

C# Example: nextItem = WebService.ddCorrect(sessionId);


ddIncorrect

C# Syntax: int ddIncorrect (int sessionId)




Returns: The integer value of the next item in the future queue (i.e., the next item to deliver in the drill), or an error code (see Appendix).

Description: The developer calls ddIncorrect when the drill-taker answers an item incorrectly. Drill Designer adds 1 to the number of times the item has been presented and answered incorrectly. All occurrences of the item are then removed from the future queue and reinserted at the positions specified in insertPositions[] during the ddCreateDrill call. Sometimes the future queue is not long enough to accommodate the insertions at the positions specified. For example, if the specified positions are 3, 8, and 17, and the future queue contains only 13 elements, no insertion can be made at position 17. When this occurs, Drill Designer uses the methods described below to lengthen the future queue and/or reduce the specified positions so that the insertions can made. Which methods are used depends upon the insertionTechnique specified during ddCreateDrill. Each insertionTechnique uses at least two of the methods, generally occurring in the order listed.

• Resurrection (used by "RDII", "RDIns", "RDInt", "RFII" and "EC") Resurrection lengthens the future queue by appending items from the retired items list to the end. 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. No more than one of each retired item is resurrected per ddIncorrect call.

• Diminishing Intervals (used by "DII", "RDII" and "RDInt")

This method reduces the distance between the insert positions. The furthest position is reduced first. For example, if the insert positions are 3, 8, and 17 and the length of the future queue is 12, then the 17 may be reduced to allow the insertions. This method cannot reduce a position lower than smallestInsertPos, passed during ddCreateDrill.

• Diminishing Insertions (used by "DII", "RDII" and "RDIns")

This method reduces the number of insert positions. For example, if the insert positions are 3, 8, and 17 and the length of the future queue is 8, then the 17 may be deleted to allow the insertions. The number of insertions cannot be less than fewestNumInsert defined during ddCreateDrill.

• Appending (used by "RDII", "RDInt", "RDIns", "RFII" and "EC")

This method uses non-retired items to lengthen the future queue. Items are merely copied from the front of the future queue and padded to the end.


Noteworthy particulars of each insertionTechnique are listed below:

• DII (Diminishing Insertions and Intervals) This technique includes no methods for lengthening the future queue, therefore it comes with a

special case: if the length of the future queue is too short to allow the smallest (first) position in insertPositions[], 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 (note, however, it does not check fewestNumInsert before deleting an insert position).

• RDII (Resurrection with Diminishing Insertions and Intervals)

This technique uses Resurrection, Diminishing Intervals, Diminishing Insertions, and Appending, generally in that order. Furthest insertion points are reduced/deleted first. Appending is only used if the earlier 3 methods have not allowed acceptable insertion, as determined by fewestNumInsert and smallestInsertPos.

• RDIns (Resurrection with Diminishing Insertions)

This technique uses Resurrection, Diminishing Insertions and Appending, in that order. Furthest insertion points are deleted first. Appending is only used if the earlier 2 methods have not allowed acceptable insertion, as determined by fewestNumInsert.

• RDInt (Resurrection with Diminishing Intervals)

This technique uses Resurrection, Diminishing Intervals and Appending, in that order. Furthest insertion points are diminished first. Appending is only used if the earlier 2 methods have not allowed acceptable insertion, as determined by smallestInsertPos.

• RFII (Resurrection with Fixed Insertions and Intervals)

This technique uses Resurrection and, if needed, Appending until the insertions can be made in the specified positions. No reduction in the number of insertions or their position is done.

• EC (Endless Continuum)

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

C# Example: nextItem = WebService.ddIncorrect(sessionId);


Commands for Retaining & Obtaining Student Performance Information Drill Designer contains several commands allowing you to determine, store, restore, and manipulate information about a drill. The first set of commands (ddStore through ddGetDeveloperVariables) enables you to save and restore a drill’s state across multiple sessions, so you can create drills that are convenient for the end user to take in several smaller pieces of time. The second set of commands (ddRetrieveInfo through ddGetHardestItemAt) lets you determine end-user performance information, which you can use to alter a drill at runtime to optimize learning.

ddStore ddRestore ddIsStudentTakingDrill ddSetDeveloperVariables ddGetDeveloperVariables ddRetrieveInfo ddRetrieveQueue ddGenerateHardestItemsList ddGetHardestItemAt


ddStore

C# Syntax: int ddStore (int sessionId)




Returns: An integer value that is either zero (0)—indicating a successful store of the drill to the database—or a negative number, which is an error code (see Appendix).

Description: ddStore is called when the developer wishes to save the user’s drill session. The entire current drill state for the user—all queues and performance information—is saved to Drill Designer’s database, and can be restored in a later session, whenever the user is ready to continue, using ddRestore. Note that ddStore must be called before ddDispose or the drill state will be lost. Also note that a developer may optionally store out additional information of use to the developer, by placing it in a “developer variables” string and calling ddSetDeveloperVariables before ddStore (see ddSetDeveloperVariables for more information). This additional information can be retrieved in a following user session by calling ddGetDeveloperVariables after ddRestore (see ddGetDeveloperVariables for more information). Finally, note that a call to ddStore passing a session created with the “$Unique$” mechanism (see description in ddCreateDrill) will generate an error. For multi-session drills involving ddStore and ddRestore, it is essential that students know and are familiar with their student ID.

C# Example: storeState = WebService.ddStore(sessionId);


ddRestore

C# Syntax: int ddRestore (

String developerId, String drillId, String studentId )





studentId The ID associated with the student taking the drill. The ID must be unique to a student within the drill and be identical to the studentId used to store the state with ddStore in order to identify the student’s saved drill state, and to prevent collisions with simultaneous users taking the same drill.

Returns: The session ID to be used for subsequent Drill Designer calls made in the same session. An error code may be returned instead of the session ID (see Appendix).

Description: To continue a multi-session drill that has been previously saved to Drill Designer’s database with ddStore, a developer uses ddRestore instead of ddCreateDrill, passing developer ID, drill ID and student ID to designate the specific drill. ddRestore returns the new session ID to use in continuing the user’s drill. Note 1: In order to know whether to call ddCreateDrill or ddRestore for a drill, a developer must be able to determine whether or not a student has already started the drill. The ddIsStudentTakingDrill call is used for this (see on following page). Note 2: If any developer variables were stored with the ddStore call (see ddSetDeveloperVariables), a separate call to ddGetDeveloperVariables must be made, following ddRestore, to obtain them (see ddGetDeveloperVariables).

C# Example: sessionId = WebService.ddRestore(developerId, uniqueDrillId, uniqueStudentId);


ddIsStudentTakingDrill

C# Syntax: int ddIsStudentTakingDrill (

String developerId, String drillId, String studentId )





studentId The ID associated with the student taking the drill. The ID must be unique to a student within the drill and be identical to the studentId used in previous sessions in order to identify the student’s saved drill state.

Returns: An integer value that can be: zero (0) meaning false, one (1) meaning true, or a negative number, which is an error code (see Appendix).

Description: A developer uses ddIsStudentTakingDrill to determine whether the student indicated by studentId is in the midst of taking drill drillId. ddIsStudentTakingDrill will return true in either of these conditions:

- A stored session for this student is in the database (meaning the student has previously taken part or all of the drill and the state has been stored using ddStore).

- An active session for this student is in memory (meaning the student is currently taking the drill). This can occur in situations where the session has not been disposed of and has not yet timed out (e.g., a student walks away from one computer and begins the drill on another).

A true return value indicates the developer may call ddRestore rather than ddCreateDrill, allowing the student to continue in the drill where he/she left off. ddRestore correctly connects the user to the existing session in either of the above scenarios. It’s worth noting that ddIsStudentTakingDrill’s return value indicates any activity the student has already had with the drill, including having completed it. A call to ddNext after ddRestore can determine whether the user has already completed the drill and appropriate action can be taken (e.g., giving them their prior score, asking them if they’d like to take the drill over, etc.).

C# Example: alreadyTaking = WebService.ddIsStudentTakingDrill(developerId, uniqueDrillId,

uniqueStudentId);


ddSetDeveloperVariables

C# Syntax: int ddSetDeveloperVariables (

int sessionId, String varName, String developerVariables )




varName A string containing a name to associate with developerVariables.

developerVariables A string containing the value(s) of one or more special variables the developer wishes to keep.

Returns: An integer value that is either zero (0)—indicating the varName/developerVariables pair was successfully set—or a negative number, which is an error code (see Appendix).

Description: A developer of a drill to be used across multiple sessions may need to maintain unique variables that are part of the drill, but outside those automatically stored and restored by Drill Designer’s ddStore and ddRestore. A mechanism involving two additional calls—ddSetDeveloperVariables and ddGetDeveloperVariables—allows developers to have these variables stored by ddStore and restored by ddRestore along with the drill state variables. The following sequence must be followed: 1) Concatenate the values of one or more variables into a developerVariables string (e.g., drillPrefs

in the C# example below). The format may be chosen by the developer (e.g., separated by commas in a desired order). Note that the string cannot contain more than 4000 characters. The characters can be Unicode characters.

2) Call ddSetDeveloperVariables, passing developerVariables and a 50-character-or-less string varName (e.g., in example “Preferences”) to associate with it for later retrieval. Drill Designer will store this name/value pair along with the drill state in the database during the next ddStore call. (Note that ddSetDeveloperVariables can be called more than once to set multiple developer variables. They will all be stored with the next ddStore call.)

3) Call ddStore as it would normally be called to save the drill state. The name/value pairs are stored. 4) In the next user session (i.e., the next time the student starts the drill), call ddRestore as it would

normally be called. The name/value pairs are restored into Drill Designer’s session memory along with the drill state.

5) Call ddGetDeveloperVariables once for each name/value pair stored. Parse any returned string, as needed, to obtain and set any individual variables that had been concatenated into it.

C# Example: devVarSet = WebService.ddSetDeveloperVariables(sessionId, “Preferences”, drillPrefs);


ddGetDeveloperVariables

C# Syntax: String ddGetDeveloperVariables (

int sessionId, String varName )




varName A string containing a name associated with a developer variable.

Returns: A string containing the value of the requested developer variable. If the passed sessionID was invalid, or varName was not specified or unrecognized, the routine will return an error message (see the Appendix for a complete list of error messages).

Description: A call to ddGetDeveloperVariables returns a string containing the value of a developer variable associated with varName that was set with a previous call to ddSetDeveloperVariables, stored with a previous call to ddStore, and restored using ddRestore. The developer must parse the returned string to obtain and set any individual variables that had been concatenated into it. For a complete description of the mechanism provided by ddSetDeveloperVariables and ddGetDeveloperVariables, see the description on the previous page.

C# Example: myDeveloperVariables = WebService.ddGetDeveloperVariables(sessionId, “Preferences”);


ddRetrieveInfo

C# Syntax: int ddRetrieveInfo(

int sessionId, InfoIdType infoId, int itemNum, int positionNum, )




infoId An enumeration specifying what information is requested.

itemNum The item number on which the indicated action is performed Note: this parameter is required only when infoId is: FQ_TIMES_PRESENT LL_TIMES_PRESENT RI_TIMES_PRESENT TIMES_MISSED TIMES_GIVEN PERCENT_MISSED

positionNum The queue position at which the indicated action is performed. Note: this parameter is required only when infoId is: FQ_ITEM_AT LL_ITEM_AT RI_ITEM_AT

Returns: The integer value requested via the infoId or a negative number error code (see Appendix).

Description: ddRetrieveInfo returns drill information requested by the developer. The infoId parameter indicates the information requested, as follows:

INFOID

EXPLANATION

FQ_LENGTH The length of the future queue is returned LL_LENGTH The length of the long list is returned RI_LENGTH The length of the retired items list is returned


FQ_TIMES_PRESENT Returns the number of times an item (itemNum) is in

the future queue LL_TIMES_PRESENT Returns the number of times an item (itemNum) is in

the long list RI_TIMES_PRESENT Returns the number of times an item (itemNum) is in

the retired items list (this is either 0 or 1). TIMES_MISSED Returns the number of times an item (itemNum) has

been missed TIMES_GIVEN Returns the number of times an item (itemNum) has

been given PERCENT_MISSED Returns the percentage of times an item (itemNum) has

been missed (rounds to nearest integer). QUESTIONS_TOTAL Returns the number of items the user has answered for

all sessions of the drill QUESTIONS_CURRENT_SESSION Returns the number of items the user has answered for

the current session only CORRECT_TOTAL Returns the number of items the user has answered

correctly for all sessions of the drill CORRECT_CURRENT_SESSION Returns the number of items the user has answered

correctly for the current session only PERCENT_CORRECT_TOTAL Returns the percentage of items that the user has

answered correctly for all sessions of the drill PERCENT_CORRECT_CURRENT_SESSION Returns the percentage of items that the user has

answered correctly for the current session only FQ_ITEM_AT Returns the item in position (positionNum) of the

future queue LL_ITEM_AT Returns the item in position (positionNum) of the

long list RI_ITEM_AT Returns the item in position (positionNum) of the

retired items list TIME_TOTAL Returns the time (in seconds) that the user has spent in

the drill for all sessions TIME_CURRENT_SESSION Returns the time (in seconds) that the user has spent in

the drill for the current session

C# Examples: Get the length of the future queue. fqLength = WebService.ddRetrieveInfo (sessionId, InfoIdType.FQ_LENGTH, 0, 0); Get the number of times item 7 is in the future queue. timesInFQ = WebService.ddRetrieveInfo (sessionId, InfoIdType.FQ_TIMES_PRESENT, 7, 0); Get the item in the 5th position in the long list. item5 = WebService.ddRetrieveInfo (sessionId, InfoIdType.LL_ITEM_AT, 0, 5); Get the total amount of time (in seconds) that the user has spent in the drill for all sessions. totalTime = WebService.ddRetrieveInfo (sessionId, InfoIdType.TIME_TOTAL, 0, 0);


ddRetrieveQueue

C# Syntax: String ddRetrieveQueue (

int sessionId, QueueType queue )




queue An enumeration that identifies the queue to retrieve (FQ = future queue, LL = long list, RI = retired items list)

Returns: Returns a string of comma-separated items from the specified queue. May also return an error message in the event of bad sessionID or bad queue being passed.

Description: ddRetrieveQueue constructs a string containing the items in the queue specified. Each of the items is separated by a comma. It is up to the drill developer to parse the string, etc. in order to accomplish any desired tasks with the string.

C# Example: Get a list of the items in the retired items list. retiredItemsListContents = ddRetrieveQueue (sessionId, QueueType.RI);


ddGenerateHardestItemsList

C# Syntax: int ddGenerateHardestItemsList (

int sessionId, int hardestItemListLength, ListFormat listFormat )




hardestItemListLength Length of the hardest items list to be generated. listFormat The method of construction (NUMBER, or

PERCENTAGE).NUMBER

Returns: The length of the hardest items list that was constructed by the call, or a negative number, which is an error code (see Appendix).

Description: This method constructs a list of the items the drill taker has had the most difficulty with and returns the length of the constructed list. After this call, the developer can call ddGetHardestItemAt (see on next page) to retrieve the actual item numbers in the list. The length returned by ddGenerateHardestItemsList is used as an upper bound for the position parameter passed to ddGetHardestItemAt. The list format is specified by parameter listFormat; this can be either NUMBER, meaning the list is constructed by the number of times the item is missed, or PERCENTAGE, 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 PERCENTAGE is used and two items have been missed every time, one missed 10 out of 10 times will be listed before one missed 5 out of 5 times). If an item has not been missed, it will not be put into the hardest items list. Thus the resultant list will not contain hardestItemListLength items if fewer items have been missed. The returned value equals the length of the list that was constructed by the call.

C# Examples: Construct a list of the items that have been missed the most number of times (which is of size 10 or

less). hardestListLength = ddGenerateHardestItemsList (sessionId, 10, ListFormat.NUMBER);

Construct a list of the items that have been missed the highest percentage of times (15 or fewer items). hardestListLength = ddGenerateHardestItemsList (sessionId, 15, ListFormat.PERCENTAGE);


ddGetHardestItemAt

C# Syntax: int ddGetHardestItemAt (

int sessionId, int position )




position An integer indicating a list position.

Returns: Returns the item in position position of the hardest items list. Returns 0 (zero) if the position requested doesn’t exist or the hardest items list has not been created (see ddGenerateHardestItemsList). May also return a negative number, which is an error code (see Appendix).

Description: ddGetHardestItemAt returns the item in position position of the hardest items list. A call should be made to ddGenerateHardestItemsList immediately preceding this one to ensure that the list is correct. If calls have been made to ddCorrect, ddIncorrect, ddPurge, etc. since the last call to ddGenerateHardestItemsList the hardest items list may no longer be up-to-date.

C# Example: Get the 5th item in the hardest items list. fifthHardest= ddGetHardestItemAt (sessionId, 5);


Drill Modification Commands While many of Drill Designer’s queuing mechanisms are automated, based upon parameters the drill developer specifies during drill creation, Drill Designer also contains several commands that allow drill developers to manually manipulate the item queues, if greater control is desired. These commands, listed and described below, complete the set of Drill Designer commands.

ddInsert ddPurge ddRequeue ddRetire ddPad ddScramble


ddInsert

C# Syntax: int ddInsert (

int sessionId, int itemNumber, int[] insertPositions, QueueType queue )



sessionId The session ID returned by ddCreateDrill or ddRestore

itemNumber The item number to be inserted insertPositions[] The positions at which to insert the item (array of

integers)

queue Identifies list to insert into (FQ=future queue, LL= long list)

FQ

Returns: A 0 (zero) if the item was inserted successfully at the specified positions, or a negative integer value which represents an error code (see Appendix).

Description: ddInsert allows the developer to modify the future queue or the long list by inserting item(s)at specified positions. To make the insertions correctly, insertPositions[] 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 none of the insertionTechnique methods used in ddIncorrect are employed. If the list isn't long enough, the insertions are made at the end.

C# Example: To insert item 5 into the long list at positions 3, 6, and 9: errorCode = ddInsert(sessionId, 5, new int[] {3, 6, 9}, QueueType.LL)


ddPurge

C# Syntax: int ddPurge (

int sessionId, ListType itemOrPosition, int[] purgeList, QueueType queue )




itemOrPosition Enumeration that indicates whether to purge items (ITEMS) or purge positions (POSITIONS)

purgeList[] the positions/items to purge (array of integers) queue Enumeration that identifies list to purge from (FQ

= future queue, LL = long list) FQ

Returns: A 0 (zero) if the purge was completed successfully, or a negative integer value which represents an error code (see Appendix).

Description: A list of integers is passed as purgeList[]. This list can signify either items or positions, depending on the value of itemOrPosition. Thus ddPurge can be used in two ways:

1) If itemOrPosition is passed as POSITIONS, then ddPurge will remove the individual items at the positions specified by purgeList from the list specified by queue.

2) If itemOrPosition is passed as ITEMS, then ddPurge will delete all instances of those items from the list (i.e., those items will no longer be present in the list).

In both cases, items that are removed do not have any status changes: they are not added to the retired items list, their number of times missed is not updated, etc. Note that current status for the item (e.g., how many times missed so far) is retained, however.

C# Example: Starting with a future queue of 2 4 6 8 10 12 14 16 18 20: errorCode = ddPurge (sessionId, ListType.POSITIONS, new int[] {3,6,9}, QueueType.FQ) The resultant future queue will be: 2 4 8 10 14 16 20 (items that were in the old positions 3, 6 and 9 gone).


ddRequeue

C# Syntax: int ddRequeue (

int sessionId, int itemNumber, int[] positions, QueueType queue )




itemNumber Indicates the item to reinsert into the queue Positions[] The positions to reinsert at (array of integers) queue Identifies list to requeue to (FQ = future queue,

LL = long list) FQ

Returns: A 0 (zero) if ddRequeue was completed successfully, or a negative integer value which represents an error code (see Appendix).

Description: ddRequeue removes an item from the specified list and reinserts it back into that list at indicated positions. ddRequeue can be thought of as a combination of ddPurge and ddInsert; it first purges an item from the list, then reinserts it. In fact, ddRequeue will act exactly like ddInsert if the item specified is not in the list already. ddRequeue cannot be used to purge items (i.e., if it is unable to perform the insertions due to an invalid list, it will not perform the deletion). Performing a ddRequeue does not change any of the data associated with an item, such as times missed and times answered.

C# Example: errorCode = ddRequeue (sessionId, 10, new int[] {2, 4, 6, 8}, QueueType.FQ)


ddRetire

C# Syntax: int ddRetire (

int sessionId, int itemNumber )




itemNumber Indicates the item to retire from the future queue

Returns: A 0 (zero) if ddRetire was completed successfully, or a negative integer value which represents an error code (see Appendix).

Description: ddRetire removes all occurrences of an item from the future queue, then retires the item by adding it to the retired items list, unless it already exists in the retired items list because it was retired earlier and resurrected. If the item is not present in the future queue, ddRetire does nothing. Note that the ddRetire operation works only on the future queue; an item cannot be retired from the long list.

C# Example: errorCode = ddRetire (sessionId, 9)


ddPad

C# Syntax: int ddPad (

int sessionId, int[] padList, QueueType queue )




padList[] The list of items to pad. queue Identifies list to requeue to (FQ = future queue,

LL = long list) FQ

Returns: A 0 (zero) if ddPad was completed successfully, or a negative integer value which represents an error code (see Appendix).

Description: ddPad adds the items specified in padList[] to the end of the list designated by queue. If an item in padList[] is non-existent, i.e., the item number is larger than the item pool size specified in ddCreateDrill, ddPad will still add the item, but a warning will appear in the next call to ddGetErrorMessage (see Appendix). ddPad 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.

C# Example: To add items 2, 4 and 6 to the end of the long list: errorCode = ddPad (sessionId, new int[] {2, 4, 6}, QueueType.LL)


ddScramble

C# Syntax: int ddScramble (

int sessionId, int numPositions )




numPositions The number of items to scramble at the front of the future queue or 0, which will scramble the entire future queue

0

Returns: A 0 (zero) if ddScramble was completed successfully, or a negative integer value which represents an error code (see Appendix).

Description: ddScramble scrambles items at the front of the future queue. ddScramble can be a useful tool to occasionally “mix up” the items the user sees. However, it should be used with care, as it can also destroy carefully prescribed insertion intervals.

C# Example: To scramble the next 5 items in the future queue: errorCode = ddScramble(sessionId, 5)


Appendix: Error Codes and Error Messages This appendix explains the difference between error codes and error messages, and provides an ordered list of all that can occur with further explanation for help debugging during drill development. Error Codes All routines that return an integer type may return an error code instead of the expected return value. Error codes are negative numbers, so a check for this can assist with bullet-proofing code. Some routines (e.g., ddStore) do not have an expected return value, and will merely return 0 when there is no error, to indicate the routine completed successfully. (Clearly, this is really a “success” code, but is included in the below table for completeness.)

Code Occurs In Command Executed? 0 (Success) ddDispose, ddStore, ddSetAuthorVariables, ddInsert,

ddPurge, ddRequeue, ddRetire, ddPad, ddScramble Yes

Explanation: Zero (0) returned for the listed routines merely indicates successful completion. Code Occurs In Command Executed?

-1 (Invalid sessionID) All routines where sessionID is passed. No Explanation: The sessionID passed was invalid. Either sessionID was erroneous or the session has timed out. Code Occurs In Command Executed?

-2 (Error occurred) ddCorrect, ddInsert, ddGetHardestItemAt, ddGetHardestItemsList, ddPad, ddRequeue

Unknown

Explanation: An error has occurred as a result of parameters passed or the condition under which the routine was called. A call to ddGetErrorMessage inserted immediately after the call producing the error will return a string with more detail about the specific error.

Code Occurs In Command Executed?

-3 (Warning occurred) ddCorrect, ddIncorrect, ddInsert, ddRequeue Yes Explanation: A warning has occurred as a result of parameters passed or the condition under which the routine

was called. A call to ddGetErrorMessage inserted immediately after the call producing the error will return a string with more detail about the specific warning.


-4 (Invalid developerID) ddCreateDrill, ddRestore No Explanation: An invalid developerID has been passed. The command could not be executed and a session could

not be returned. To be valid a developerID must exactly match the developerID provided to you through the Drill Designer information & registration site (see section “Requirements for Using Drill Designer” earlier in this manual). Note that any leading or trailing space characters passed are ignored.


-5 (Database error) ddCreateDrill, ddRestore, ddIsStudentTakingDrill, ddStore

Unknown

Explanation: An error has occurred, due to a problem with the Drill Designer database. Please contact the Drill Designer administrator. With ddStore, a call to ddGetErrorMessage immediately following ddStore will return more specific information about the error. With ddCreateDrill and ddRestore, a session ID was not returned.


-6 (Invalid drillID) ddCreateDrill, ddIsStudentTakingDrill, ddRestore No Explanation: An invalid drillID has been passed. The command could not be executed and a session could not

be returned. Valid drillIDs must contain at least one non-space character, be less than or equal to 50 characters in length, and contain no control characters (0 – 30 and 127). Any leading or trailing blanks are ignored.



-7 (Invalid studentID) ddCreateDrill, ddIsStudentTakingDrill, ddRestore No Explanation: An invalid studentID has been passed. The command could not be executed and a session could

not be returned. Valid studentIDs must contain at least one non-space character, be less than or equal to 100 characters in length, and contain no control characters (0 – 30 and 127). Any leading or trailing blanks are ignored.


-8 (drillID not in database) ddRestore No Explanation: A drillID has been passed that could not be found in the database. The command could not be

executed and a session could not be returned. Code Occurs In Command Executed?

-9 (studentID not in database) ddRestore No Explanation: A studentID has been passed that could not be found in the database. The command could not be

executed and a session could not be returned. Code Occurs In Command Executed?

-10 (developerID not in database) ddRestore No Explanation: A developerID has been passed that could not be found in the database. The command could not

be executed and a session could not be returned. The passed developerID must exactly match the developerID provided to you through the Drill Designer information & registration site (see section “Requirements for Using Drill Designer” earlier in this manual).


-11 (generated ID limit exceeded) ddCreateDrill No Explanation: The limit of 100 simultaneous generated student IDs/session IDs has been exceeded. This error

occurs when a developer is passing “$Unique$” for studentId to have Drill Designer generate the student ID and return a session ID. This limit of 100 is not in place for developer-supplied student IDs.

Error Messages A call to ddGetErrorMessage immediately following another Drill Designer call will return a string containing any error messages generated by the previous call. Note that this is true only if a valid sessionID—the same one in effect during the previous call—is passed. Also note that ddGetErrorMessage, ddGetAuthorVariables, and ddRetrieveQueue—the only Drill Designer routines that return strings—have the unique ability to return an error message string directly. They do this in the event that a bad sessionID is passed.

Message Occurs In Command Executed? Consecutive items could not be shuffled,

duplicates possibly removed. ddCorrect, ddIncorrect, ddInsert, ddPurge, ddRequeue, ddRetire, ddScramble

Yes

Explanation: Drill Designer makes every attempt to prevent the same item from appearing consecutively in a queue. An attempt is made to shuffle consecutive items, but when this cannot be done, duplicate items are removed from the queue. Note that unshuffled consecutive items are not removed after ddCreateDrill.

Message Occurs In Command Executed?

Developer variable (varName = <varname>) not found.

ddGetDeveloperVariables No

Explanation: The developer variable specified in the varName parameter was not found. Verify that the name you’re requesting is the same name that was used when it was created with ddSetDeveloperVariables.



Developer variable name not provided. ddGetDeveloperVariables, ddSetDeveloperVariables

No

Explanation: The parameter varName was not specified. Message Occurs In Command Executed?

Developer variable name <varname> was too long, variable ignored.

ddSetDeveloperVariables No

Explanation: Parameter varName was longer than the maximum length of 50 characters, therefore the variable was not set. Note that the name may contain Unicode characters.


Developer variable too long, truncated to 4000 characters.

ddSetDeveloperVariables Yes

Explanation: The developerVariables parameter passed to ddSetDeveloperVariables was too long. The string cannot be longer than 4000 characters and therefore the string was truncated.


fewestNumInsert invalid, default value taken. ddCreateDrill Yes Explanation: The parameter passed to ddCreateDrill for fewestNumInsert was out of range. The fewest number

of insertions allowed for diminishing insertions, which is a required parameter for insertionTechnique of RDII or RDIns, must be greater than 0 and less than or equal to the number of insert positions specified in insertPositions. A default has been taken of 1.


fewestNumInsert or smallestInsertPos criteria not satisfied.

ddIncorrect Yes

Explanation: Diminishing of insertions and/or intervals occurred when handling insertions during ddIncorrect. One or both of the criteria that constrain diminishing could not be satisfied.


Future queue has no items in it, it is empty. ddCorrect, ddIncorrect No Explanation: A call has been made indicating an action to be taken upon the future queue that cannot be

completed because the future queue has no items in it. The future queue is empty. Message Occurs In Command Executed?

Future queue not long enough for replenishPositions.

ddCorrect, ddPurge, ddRetire Yes

Explanation: Replenishing has been triggered. The future queue is not long enough for replenishing to occur at the positions specified in replenishPositions. For all positions beyond the length of the future queue, replenishing will simply occur at the end of the future queue.


Hardest items list is empty. ddGetHardestItemAt No Explanation: A call has been made to ddGetHardestItemAt, but the hardest items list has not been created. Be

sure to call ddGenerateHardestItemsList before calling ddGetHardestItemAt. Message Occurs In Command Executed?

Hardest items list length was invalid. ddGenerateHardestItemsList No Explanation: The hardestItemsListLength parameter passed to ddGenerateHardestItemsList is invalid (e.g., it

cannot be negative). The command was not executed. Message Occurs In Command Executed?

Hardest items list position is out of range. ddGetHardestItemAt No Explanation: The position parameter passed to ddGetHardestItemAt is out of range for the hardest items list

created during the last call to ddGenerateHardestItemAt.



Insert positions invalid or not in increasing order.

ddInsert, ddRequeue No

Explanation: The parameter passed for insertion positions was invalid. The insert positions to be used with cannot be empty, nor list more than 10 positions. Also, positions must be listed in increasing order, and each position must be greater than 0, but less than 10,000.


insertPositions invalid, default positions taken.

ddCreateDrill Yes

Explanation: The parameter passed to ddCreateDrill for insertPositions was invalid. The insert positions to be used with ddIncorrect cannot be empty, nor list more than 10 positions. Also, positions must be listed in increasing order, and each position must be greater than 0, but less than a reasonable future queue position as defined by (numFutureQueueItems * numRepeat + 1) when numFutureQueueItems > 0, or (questionPoolSize * numRepeat + 1). A default of {3, 8, 17} has been taken.


Item not found in future queue. ddRetire No Explanation: The itemNumber parameter passed to ddRetire was not found in the future queue and could not be

retired. Message Occurs In Command Executed?

Item number greater than questionPoolSize. ddInsert, ddPad, ddRequeue Yes Explanation: An item number has been specified that is larger than questionPoolSize. The command has been

executed, but this message is a warning to the developer in that this may have been unintentional and could cause problems to the execution of the drill.


Item number invalid, command not executed. ddInsert, ddRequeue No Explanation: An invalid item number has been specified. The command could not be executed. Item numbers

cannot be less than 1 or greater than 10,000. Message Occurs In Command Executed?

itemOrPosition invalid, command not executed.

ddPurge No

Explanation: An invalid value was passed to ddPurge for parameter itemOrPosition. The command was not executed.


listFormat invalid, default value taken. ddGenerateHardestItemsList Yes Explanation: An invalid value was passed to ddGenerateHardestItemsList for parameter listFormat. The default

value of NUMBER has been taken. Message Occurs In Command Executed?

numFutureQueueItems invalid, default value taken.

ddCreateDrill Yes

Explanation: The parameter passed to ddCreateDrill for numFutureQueueItems was out of range. The number of different items to initially be in the future queue cannot be less than 0, nor greater than 10,000. A default has been taken of questionPoolSize, if valid, or 20.


numPositions invalid, default value taken. ddScramble Yes Explanation: The parameter passed to ddScramble for numPositions was out of range. The number of items to

scramble at the front of the future queue cannot be negative or greater than the length of the future queue. The default value of 0 (zero) has been taken, which causes the entire future queue to be scrambled.



numRepeat invalid, default value taken. ddCreateDrill Yes Explanation: The parameter passed to ddCreateDrill for numRepeat was out of range. The number of times to

present the initial future queue cannot be less than 0 or greater than 10. The default value of 1 has been taken.


numRetiresToReplenish invalid, default value taken.

ddCreateDrill Yes

Explanation: The parameter passed to ddCreateDrill for numRetiresToReplenish was out of range. The number of items to retire before replenishing occurs, which is a required parameter for insertTechnique of EC, must be greater than 0 and less than or equal to numFutureQueueItems (when numFutureQueueItems > 0) or questionPoolSize. A default has been taken of 1.


padList invalid, command not executed. ddPad No Explanation: The padList parameter passed to ddPad was invalid or out of range. The padList parameter cannot

be empty and cannot contain items less than 1 or greater than 10,000. Message Occurs In Command Executed?

Parameter invalid or out of range. ddRetrieveInfo Unknown Explanation: A parameter passed to ddRetrieveInfo was invalid or out of range. Please check the ddRetrieveInfo

command in the manual and ensure you are correctly specifying parameters. Message Occurs In Command Executed?

purgeList invalid, command not executed. ddPurge No Explanation: The purgeList parameter passed to ddPurge was invalid. The command was not executed. Values

in purgeList must be valid items or positions (depending upon the itemOrPosition parameter). Message Occurs In Command Executed?

questionPoolSize invalid, default value taken. ddCreateDrill Yes Explanation: The parameter passed to ddCreateDrill for questionPoolSize was out of range. The total number of

items in the drill cannot be less than numFutureQueueItems, nor less than 1, nor greater than 10,000. A default has been taken of numFutureQueueItems, if valid, or 20.


queue ID passed was invalid. ddInsert, ddPad, ddRequeue, ddRetrieveQueue, ddPurge

No

Explanation: The queue passed was invalid, and so the requested queue could not be determined. Valid parameters are indicated in the manual explanation of the specific command you were calling.

Message Occurs In Command Executed? replenishPositions invalid, default positions

taken. ddCreateDrill Yes

Explanation: The parameter passed to ddCreateDrill for replenishPositions was invalid. The positions to use when replenishing, which is a required parameter for insertTechnique of EC, cannot be empty, nor list more than 10 positons. Also, positions must be listed in increasing order, and each position must be greater than 0, but less than a reasonable position as defined by questionPoolSize * numRepeat + 1.


Session already present in memory, overwritten by new session.

ddCreateDrill Yes

Explanation: A session was found already existing in memory for the developerID, drillID, studentID combination passed to ddCreateDrill. Since the request was to create a new drill, the existing session was overwritten by a session for a new drill.



Session already present in memory, not restored from database.

ddRestore Yes

Explanation: A session was found already existing in memory for the developerID, drillID, studentID combination passed to ddRestore. Since the request was to restore this drill, the session found in memory was returned for the student to continue.


sessionID was not found. The session may have expired.

ddGetDeveloperVariables, ddGetErrorMessage

No

Explanation: A session was not found in memory for the sessionID that was passed. The session may have expired or the sessionID may contain an error.


smallestInsertPos invalid, default value taken.

ddCreateDrill Yes

Explanation: The parameter passed to ddCreateDrill for smallestInsertPos was out of range. The smallest insert position allowed for diminishing intervals, which is a required parameter for insertionTechnique of DII, RDII, or RDInt, must be greater than 0 and less than or equal to the largest position in insertPositions[]. A default has been taken of 1.


Unable to store generic session. ddStore No Explanation: The sessionID passed to ddStore is one that was created with the “$Unique$” mechanism (see

description in ddCreateDrill) and is not allowed to be stored. For multi-session drills involving ddStore and ddRestore, it is essential that students know and are familiar with their student ID. You must call ddCreateDrill passing such a student ID and the returned session ID will allow store and restore to occur.

drill designer web service - ddra.its.uiowa.edus... · drill designer web service user/developer...

Documents