Dasher Web Service USER/DEVELOPER DOCUMENTATION June 2010 Version 1.1

Transcription

1 Dasher Web Service USER/DEVELOPER DOCUMENTATION June 2010 Version 1.1 Credit for the instructional design theory and algorithms employed by Dasher goes to James Pusack and Sue Otto of The University of Iowa Copyright James P. Pusack, Sue K. Otto and The University of Iowa 1

2 Table of Contents Getting Started With Dasher... 4 The Purpose of Dasher... 4 Requirements for Using Dasher... 4 Dasher Overview... 5 Simple Dasher Program Flow... 5 Using this Manual... 7 Notes on Parameter Formats... 7 Core Dasher Commands... 8 dasherinit... 9 dashermarkup dashergetobject dasherdispose dashermessage Commands for Obtaining Response Difference Information dashergetresponseinfo dashergetfeedback Commands for Customizing Dasher dashersetcasematters dashersetjudgewholewords dashersetcriticallength dashersetauthormarks dashergetauthormarks dashersetmarkupcharacters dashergetmarkupcharacters dashersetnonjudgedcharacters dashergetnonjudgedcharacters dashersetjudgedcharacters dashergetjudgedcharacters dashersetfillinblank dashergetfillinblank Command that Supports Authors dashercheckitem Commands that Support Fill-in-the-Blank Formats dashermakefillin dashergetfillinprompt Copyright James P. Pusack, Sue K. Otto and The University of Iowa 2

3 dashergetfillinobj dashergetfillinresponse Appendix A: Error Codes and Error Messages Error Codes Error Messages Appendix B: Multiple Correct Objects Appendix C: How Dasher Analyzes Copyright James P. Pusack, Sue K. Otto and The University of Iowa 3

4 Getting Started With Dasher This section contains information that will help you get started with Dasher, explaining 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 "Core Dasher Commands," before attempting to produce an application with Dasher. The Purpose of Dasher Dasher is a tool that educators can employ to create exercises to facilitate student learning, particularly in (but not limited to) the foreign language field. Dasher exercises enable students to locate mistakes in their text responses and correct them efficiently without verbose explanations. The author (perhaps an instructor or instructors' aide) creates exercises consisting of a prompt with a "correct" response that we call the object. Students type their response, and Dasher compares their response to the correct response, or object. Dasher can return a string of text that reflects how close the student's answer came to matching the object. In general, letters or characters in the student response that match those in the object are left alone, while erroneous characters are replaced with another character of some kind, usually a dash (-), hence the name Dasher. The student can then continue to fill in the dashes with the correct characters. In this way Dasher guides the student toward an increasingly accurate response without resorting to grammatical terminology or arduous anticipation of errors that the student might conceivably make. This combination of effective error diagnosis and efficient authoring is what makes Dasher successful. Requirements for Using Dasher Dasher is provided as a web service accessible through the Simple Object Access Protocol (SOAP). You will not need to know details about SOAP but you should have a basic understanding of web services. These topics are beyond the scope of this manual. Any web application development tool that supports SOAP can call Dasher routines. This includes the vast majority of languages and tools (Flash, PHP,.NET development languages, JAVA, JavaScript, etc.). Developers should have a good working knowledge of the programming languages and tools they will use. Developers must have a developer ID (identifier), which can be obtained from the Dasher Information and Registration website at: Along with their ID, developers will receive information clarifying the 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 Dasher with specific programming languages. In order to use Dasher effectively, developers must also have an understanding of the concepts employed in Dasher and detailed knowledge of how routines operate. This document provides comprehensive information on both of these topics. Copyright James P. Pusack, Sue K. Otto and The University of Iowa 4

5 Dasher Overview Dasher is a set of author-customizable routines that control the process of comparing student responses to "correct" responses (objects) and supplying a resultant marked-up string to the student for their next attempt. For each exercise the author provides a correct or idealized response, called the "object string" (a string of characters the author expects the user to enter); the user response is the "response string" (the string entered by the user in response to a prompt in an exercise). Dasher compares the object and response strings, then returns a value designating whether or not the response string "matches" the object. Dasher also can return the response string in "marked up" form, that is, with characters such as dashes designating where the student has made an error. Dasher attempts to match up as much of the response string to the object string as possible. Normally the author will then allow the user to continue attempting to fill in the remaining portions of the item, and resubmit the new response string, giving the student a certain number of attempts or allowing them to continue until the responses match exactly. Simple Dasher Program Flow The description below outlines the basic flow of an application s interactions with Dasher. dasherinit is the command that sets up everything, and therefore is the first command called. The developer provides some information used in creating a unique session ID, which dasherinit returns, required by following calls pertaining to the same interaction. You may also specify a language that will setup appropriate default judged and non-judged character sets. dashermessage is used while testing an application during development. A call to dashermessage returns a string containing any error messages and warnings resulting from the previous call. When application testing has been completed, the developer can remove dashermessage calls. This command can be called after each call to Dasher to verify behavior. dasherset routines may optionally be utilized here to customize the behavior of Dasher. See the section "Commands for Customizing Dasher" for details on these routines. Also see Appendix C for a description of Dasher s algorithm, which will be helpful in understanding how to customize settings. Then, the flow becomes a loop The user is presented with a prompt and types a response (the response string). The author calls dashermarkup, passing the object and response strings. If dashermarkup returns true (1), the strings match, and the next item is presented. If dashermarkup returns false (0), the strings do not match exactly. A further call to dashergetmarkedresponse supplies the marked up response, with characters or sections of text the user got correct intact and with dashes inserted in locations where there were incorrect or missing characters. Other special symbols are inserted in locations where there were extra characters at the beginning, at the end or in the middle of words. (See the section on dashersetmarkupcharacters for further detail.) The student is usually allowed to fix the incorrect parts of the response and submit it again, in which case another call to dashermarkup is made. dashergetresponseinfo and dashergetfeedback routines may be utilized to obtain more information about the differences that were found in the response string and to provide additional diagnostic feedback when appropriate. until the interaction is complete, that is, until the student either types the correct answer or gives up and asks for the correct answer. Copyright James P. Pusack, Sue K. Otto and The University of Iowa 5

6 When an application has finished using Dasher, e.g., when the user chooses to quit, the developer calls dasherdispose, which frees the memory used by the Dasher session on the server. Copyright James P. Pusack, Sue K. Otto and The University of Iowa 6

7 Using this Manual The commands dasherinit, dashermarkup, dashergetmarkedresponse, and dasherdispose form the core of Dasher. Many developers can provide adequate answer judging using just these four commands, and using Dasher s default settings. These are covered in the first section, "Core Dasher Commands." Many developers will also find the command dashermessage essential. Calling dashermessage immediately following any other Dasher call, returns a string containing any error messages the previous call produced. Since this information can be essential in debugging, dashermessage is included along with dasherinit, dashermarkup, dashergetmarkedresponse, and dasherdispose in the "Core Dasher Commands" section. The commands listed in the second section, entitled "Commands for Obtaining Response Difference Information," are useful when a developer wants to provide additional diagnostic messages to students about how the response differed from the object (for example, " You have the right words in the wrong order.") The third section, "Commands for Customizing Dasher," contains numerous commands allowing a developer to adjust many aspects of Dasher. Each of these commands, whose names begin with "dasherset," allows customization of a particular aspect affecting pre-processing or comparison stages. For example, since Dasher is UNICODE-enabled, sets of characters and words can be adjusted to provide for analysis of response strings in German, French, Spanish, English or another language of your choice. In addition most dasherset commands have a corresponding dasherget command that returns current settings. Notes on Parameter Formats Each description of a Dasher 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) can be found at the Dasher Information and Registration website (see Requirements for Using Dasher). 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. Copyright James P. Pusack, Sue K. Otto and The University of Iowa 7

8 Core Dasher Commands As mentioned earlier in the description of simple program flow, there are four commands that form the core of Dasher: dasherinit dashermarkup dashergetmarkedresponse dasherdispose These commands, along with dashergetobject dashermessage are described in this section. Using these commands alone, with default settings, developers can provide adequate answer judging for many applications. (Other commands, described in the section "Commands for Customizing Dasher", can be used to change the defaults). Copyright James P. Pusack, Sue K. Otto and The University of Iowa 8

9 dasherinit int dasherinit ( string developerid, string interactionid, string studentid, string language ) developerid interactionid studentid language The unique developer ID given to each developer during registration. A name (e.g., "citynames") uniquely identifying the set of interactions this application makes with Dasher from those made by other applications by the same developer. interactionid is used in creating the returned session ID that is passed in following calls. The ID associated with the student or user of the application. The ID must be unique to a student/user within the application to prevent collisions with simultaneous users. The literal string "$Unique$" may be passed to have a unique student ID generated by Dasher. Dasher will supply default judged and non-judged character sets for any of the following languages: English, French, German, Italian, Latin, Portuguese, and Spanish. You can supply an empty string and then call dashersetjudgedcharacters and dashersetnonjudgedcharacters to setup other alphabetic languages. The session ID to be used for subsequent Dasher calls made in the same session. An error code may be returned instead of the session ID (see Appendix A). Description: dasherinit must be called once by any application that uses Dasher, and must be called before any other Dasher routines can be called. dasherinit initializes the judged and non-judged character sets. Judged characters include all the letters, numbers, accented letters and other special symbols needed to type the target language. It is these characters that Dasher judges in the students' answers. The non-judged characters are ones that Dasher doesn't check when judging students' answers that is, characters that may be present in the object string that are not counted as wrong if they are missing from the student's response. Punctuation marks (periods, question marks, commas, semicolons, etc.) are usually included in the nonjudged character set so that, for example, a missing period or comma does not cause an otherwise correct response to be judged as incorrect. Copyright James P. Pusack, Sue K. Otto and The University of Iowa 9

10 dasherinit takes four parameters to create a unique session that is used by following calls from the same client-side application instance. dasherinit returns a session ID referencing the session. All other Dasher routines pass this session ID as a first parameter. Note: as a convenience for developers when a unique student ID is not obtainable, a studentid of $Unique$ may be passed, causing Dasher 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 interaction. Also note that the 100 student limit is not in place when regular student IDs are supplied by the developer. To set the language parameter to one of the currently supported languages, supply the name of the language: FRENCH, GERMAN, ITALIAN, PORTUGUESE, SPANISH, LATIN. If you pass an empty string for the language parameter Dasher will default to English. You can then call dashersetjudgedcharacters and dashersetnonjudgedcharacters to extend Dasher to a language of your choice. However Dasher does not support character-based languages, such as Japanese. Also Dasher has not been tested with alphabetic languages read from right to left such as Arabic. The default character sets, and rules set by dasherinit are described in the section "Commands for Customizing Dasher," along with the descriptions of the commands used in modifying them. The default settings enable Dasher style markup that is adequate for many applications. int = WebService.dasherInit(developerId, InteractionId, StudentId, language); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 10

11 dashermarkup int dashermarkup ( int, string obj, string resp ) obj resp The correct answer string of characters the student/user is expected to enter to be exactly matched (referred to as the "object string"). The string of characters the student/user entered (the "response string"). An integer value that can be: zero (0) meaning false, one (1) meaning true, or a negative number, indicating an error code (see Appendix A). Description: dashermarkup is the primary Dasher routine. It takes as parameters an "object string" a correct answer string the student/user is expected to enter to be exactly matched and a "response string" the actual string the student/user entered. dashermarkup compares the object and response strings, returning an indication of whether the response string matches the object string. The return value is 1 if the two strings matched, and 0 if they did not. Both the object and response must be limited to a maximum of 500 characters. Dasher supports multiple correct objects by looking for special formatting of the "object string." This advanced feature is described in Appendix B: Multiple Correct Objects. In addition Dasher supports fill-in-the-blank formats described in dashermakefillin. string object = This is a test ; string response = This is test ; int markupresult = WebService.dasherMarkup(, object, response); if (markupresult = 1) { //Handle successful match } else { //Handle failed match } Copyright James P. Pusack, Sue K. Otto and The University of Iowa 11

12 dashergetmarkedresponse string dashergetmarkedresponse (int ) A string that can be used as a starting point for the user s next response or an empty string if an invalid session ID is supplied. Description: dashergetmarkedresponse returns a string containing the marked up response based on the author's settings. In general correct characters in the response are left alone, while incorrect areas are marked with dashes. Other symbols that may be inserted into the marked response include: extra character(s) within a word, extra character(s) at the beginning of a word, and extra character(s) at the end of a word. For more information on how strings are compared by dashermarkup, see Appendix C: How Dasher Analyzes. string markedresponse = WebService.dasherGetMarkedResponse(); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 12

13 dashergetobject string dashergetobject (int ) the alternate object string Dasher determines is closest to the response string on the prior call to dashermarkup. Description: dashergetobject is used when the object passed into the prior call to dashermarkup has alternates, that is, when an object string contains multiple objects (denoted by / characters). Dasher determines which alternate is closest to the user s response. If the response was empty, Dasher constructs the object from the default (last) alternate. An author can call dashermarkup with an empty response string and then call dashergetobject to obtain the default object. Also after calling dashermarkup with a user s response, call dashergetobject to obtain the alternate that Dasher has chosen as closest to the user s response. See Appendix B: Multiple Correct Objects. string obj = WebService.dasherGetObject(); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 13

14 dasherdispose int dasherdispose (int ) A 0 (zero) if successful, or an error code (see Appendix A). Description: dasherdispose frees the memory used by a Dasher session (identified by ). When an application that uses Dasher has finished (for example, when the user has requested to quit) dasherdispose should be called to cleanly free memory utilized during the session s interactions. If dasherdispose is not called, the session will eventually timeout and be cleared from memory, but until then, memory is being wasted by an unused session. int disposestate = WebService.dasherDispose(); if (disposestate < 0) { //Handle dispose failure } Copyright James P. Pusack, Sue K. Otto and The University of Iowa 14

15 dashermessage string dashermessage (int ) A string containing one or more error messages generated during the previous Dasher call, or an empty string indicating that no error occurred. Description: dashermessage returns a string containing the error message(s) that were generated by the previous Dasher call. dashermessage is useful for the developer while creating an application to ensure that all commands are recognized and that parameters are appropriate. Once the application is executing correctly, calls to dashermessage may be removed at the developer s discretion. When there is no error or warning from the previous call, dashermessage returns an empty string. Therefore, testing for a zero-length return string can be used as a flag. All error messages are listed in Appendix A, 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. For any of these where a valid session ID is still held, a following call to dashermessage may provide more detail. See Appendix A for details of both error codes and error messages. dashermessage itself does not generate error messages or change the last message generated by another call. string errmsg = WebService.dasherMessage(); if (errmsg.length > 0) { //Report error message. } Copyright James P. Pusack, Sue K. Otto and The University of Iowa 15

16 Commands for Obtaining Response Difference Information Dasher contains several commands allowing you to obtain information about differences between the object and response. While dashermarkup, dashergetmarkedresponse and dashergetobject all return a true or false value (based on whether there was an exact match), two other commands allow you to retrieve specialized information about differences. dashergetresponseinfo dashergetfeedback dashergetresponseinfo string dashergetresponseinfo (int ) Returns more information on the latest response evaluated by a call to dashermarkup. Returns a list of boolean (0 or 1) items. dashergetresponseinfo returns a string containing a comma separated list of boolean (0 or 1) values, corresponding to whether each of the following conditions is met: List item 0: Set to 1 when response was perfect List item 1: the response only has non-judged characters. No marked up string is available. List item 2: the response is perfect except for case. This is only set when casematters is false, so the response should be considered perfect. No marked up string or feedback is available. List item 3: response is correct except for some non-judged character, so the response should be considered perfect. No marked up string or feedback is available. List item 4: feedback is available from dashergetfeedback (when this is set one of the items from 5 through 9 will also be set). List item 5: not all words are present and there are more words in response than in object List item 6: all words are present plus some addition ones. List item 7: not all words are present and some right words are in the wrong order List item 8: all words are present but not in the right order List item 9: everything is perfect except diacritical mark(s). string responseinfo = WebService.dasherGetResponseInfo(); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 16

17 dashergetfeedback string dashergetfeedback (int ) When a call to dashergetresponseinfo indicates that feedback is available an appropriate message is returned based on the type of mismatch. The string may be empty if no feedback is available or if an invalid session ID is supplied. Description: One of the following messages is returned based on the value of list items 5 through 9 described in the call to dashergetresponseinfo: - Check for extra words or spaces. - You have too many words or spaces. - Check the word order in your answer. - You have the right words in the wrong order. - Watch out! An accent or some other detail is incorrect. string feedbackmsg= WebService dashergetfeedback (); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 17

18 Commands for Customizing Dasher Dasher also contains a set of commands that allow a developer to adjust many aspects of Dasher s processing mechanism. These commands all begin with "dasherset." Appendix C provides a detailed description of Dasher s entire analysis process. Reviewing Appendix C can help in using and understanding the commands in this section. Many of the commands also have a corresponding "dasherget " that returns the current state. dashersetcasematters dashersetjudgewholewords dashersetcriticallength dashersetauthormarks (and dashergetauthormarks) dashersetmarkupcharacters (and dashergetmarkupcharacters) dashersetnonjudgedcharacters (and dashergetnonjudgedcharacters) dashersetjudgedcharacters (and dashergetjudgedcharacters) dashersetfillinblank (and dashergetfillinblank) dashersetcasematters int dashersetcasematters ( int, bool casematters ) casematters A Boolean setting whether Dasher should consider capitalization when marking a response. false A 0 (zero) if case matters was set, or a negative number indicating an error code (see Appendix A). Description: If casematters is passed as true, then Dasher will mark capitalization discrepancies as errors when comparing the object string and the response string. int returnvalue = WebService dashersetcasematters(, true); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 18

19 dashersetjudgewholewords int dashersetjudgewholewords ( int, bool judgewholewords ) judgewholewords A Boolean that sets whether Dasher mark an entire word as wrong if any judged character within it is incorrect. false A 0 (zero) if command completed successfully, or a negative number indicating an error code (see Appendix A). Description: If true is passed in judgewholewords, then a word in the response string will be judged entirely incorrect if any character within is incorrect. int returnvalue = WebService.raSetWbChars(, mywordbreakstr); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 19

20 dashersetcriticallength int dashersetcriticallength ( int, int criticallength ) criticallength Sets how many characters Dasher considers when determining which alternate object is most like the response. Only values from 2 to 4 are acceptable. 3 A 0 (zero) if command completed successfully, or a negative number indicating an error code (see Appendix A). Description: See Appendix B: Multiple Correct Objects. int returnvalue = WebService dashersetcriticallength(, criticallength); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 20

21 dashersetauthormarks int dashersetauthormarks ( int, string authormarks ) authormarks A string containing the characters Dasher should use when constructing fill in items and items that contain alternate answers. {}/*<> A 0 (zero) if command completed successfully, or a negative number indicating an error code (see Appendix A). Description: Use this command if you need to use any of the characters in your object string that Dasher uses for the special fill-in or multiple correct answer formats. When making this call, you must supply all six characters. The first two characters are used to indicate where blanks are located in the special fill-in-the-blank format. (See dashermakefillin.) The next (third) character is used to separate alternate objects. The fourth character is used to lead into a numeric value that overrides the global critical length value. The fifth and sixth characters are used to delimit a block of alternate objects. See Appendix B: Multiple Correct Objects. C# Examples: int returnvalue = WebService dashersetauthormarks(sessionid, authormarks); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 21

22 dashergetauthormarks string dashergetauthormarks ( int ) The current author marks or an empty string if an invalid sessionid is supplied. C# Examples: string authormarks = WebService dashergetauthormarks(sessionid); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 22

23 dashersetmarkupcharacters int dashersetmarkupcharacters ( int, string markupcharacters ) markupcharacters A string containing the characters that Dasher inserts in the response to indicate errors. ±= A 0 (zero) if command completed successfully, or a negative number indicating an error code (see Appendix A). Description: Use this command if you need to use any of the characters in your object string that Dasher uses when marking up the students response. The first character is used to indicate one or more extra characters behind a word. The second is used when extra characters are found in front of a word. The third indicates extra characters within a word. The fourth is the dash indicating an incorrect character. The fifth is used to indicate where the student should type in the special fill-in-the-blank format. (See dashermakefillin.) When making this call you must supply all five characters. int returnvalue = WebService dashersetmarkupcharacters(sessionid, markupcharacters); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 23

24 dashergetmarkupcharacters string dashergetmarkupcharacters ( int ) The current markup characters or an empty string if an invalid sessionid is supplied. string markupcharacters = WebService dashergetmarkupcharacters(sessionid); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 24

25 dashersetnonjudgedcharacters int dashersetnonjudgedcharacters ( int, string nonjudgedcharacters ) nonjudgedcharacters A string containing characters Dasher does not consider when marking the response. ;:.,!? added for Spanish A 0 (zero) if command completed successfully, or a negative number indicating an error code (see Appendix A). Description: Specifies the set of characters that are not considered when judging the response. Note that if you specify a character as non-judged and it is currently in the set of judged characters it will be removed from that set. int returnvalue = WebService dashersetnonjudgedcharacters (, nonjudgedcharacters); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 25

26 dashergetnonjudgedcharacters string dashergetnonjudgedcharacters ( int ) The current non-judged characters or an empty string if an invalid sessionid is supplied. Description: Returns the set of non-judged characters. These characters are not considered when judging a response. string nonjudged = WebService dashergetnonjudgedcharacters (); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 26

27 dashersetjudgedcharacters int dashersetjudgedcharacters ( int, string judgedcharacters ) judgedcharacters A string containing characters considered when marking the response. See below A 0 (zero) if command completed successfully, or a negative number indicating an error code (see Appendix A). Description: The default judged characters depend on the language supplied with the dasherinit command. Normally this includes upper and lowercase letters as well as numbers, but not punctuation marks. All languages: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz Other defined languages add additional characters as follows. FRENCH: àèùççééâêîôûë GERMAN: äöüäöüßé ITALIAN: áéíóúèàèìòù LATIN: āēīōū PORTUGUESE: ÀÁÂÃÉÊÍÓÔÕÚÜàáâãéêíóôõúüÇç SPANISH: áéíóúññü Because Dasher is Unicode compatible this command facilitates defining language character sets not predefined by Dasher. Any character that you want students to be responsible for typing in order to complete an exercise should be in the Judged Characters set. The ability to modify this set is included because in certain languages or situations other characters may be important in the string comparison process for an exercise, for example the hyphen in French, or a dollar sign in English. If the author wants Dasher to check for correct punctuation, these characters can be added as needed. Note that if you specify a character as judged and it is currently in the non-judged set, it will be removed from the non-judged set. int returnvalue = WebService dashersetjudgedcharacters (, judgedcharacters); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 27

28 dashergetjudgedcharacters string dashergetjudgedcharacters ( int ) The current judged characters or an empty string if an invalid sessionid is supplied. Description: Returns the set of characters that is used for comparisons between strings. string judged = WebService dashergetjudgedcharacters (); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 28

29 dashersetfillinblank int dashersetfillinblank ( int, string fillinblank ) fillinblank A string used when Dasher forms the prompt (question) in fill-in-the-blank items. <-----> A 0 (zero) if command completed successfully, or a negative number indicating an error code (see Appendix A). Description: Fill-in-the-blank consists of a short answer in the context of a prompt. For example, "My uncle's son is my <----->" would be answered with "cousin". The call to dashersetfillinblank determines the characters that are substituted for the blank in the prompt. See the command dashermakefillin for more information. int returnvalue = WebService.dasherSetFillInBlank (, theblank); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 29

30 dashergetfillinblank string dashergetfillinblank ( int ) The current fill-in blank or an empty string if an invalid sessionid is supplied. Description: See dashermakefillin for more information. string fillinblank = WebService dashergetfillinblank (); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 30

31 Command that Supports Authors dashercheckitem int dashercheckitem ( int, string prompt, string obj ) prompt obj The string of characters you will show to elicit a response. The string of characters the user is expected to enter. A 0 (zero) if command completed successfully, or a negative number indicating an error code (see Appendix A). Description: If dashercheckitem returns a negative value, you can call dashermessage to determine why. The following checks are made: Object has character(s) not declared as "judged" or "non-judged." This object has no characters in the "judged" character set. The marks indicating an arrow-format alternate are not in pairs. An alternate object has a pattern flag but is missing the digit that must follow. The last alternate must not have a pattern flag. A critical portion of the alternate is found elsewhere in the answer. The marks indicating a blank are not in pairs. An object with an embedded fill-in must not contain alternates. Objects that use the slash format must end with a slash. Incorrect alternate format. Each alternate group must be closed with '>'. int returnvalue = WebService dashercheckitem (, prompt, obj); if (returnvalue < 0) { String msg = WebService.dasherMessage(); //Display the message. } Copyright James P. Pusack, Sue K. Otto and The University of Iowa 31

32 Commands that Support Fill-in-the-Blank Formats Fill-in-the-blank consists of a short answer object in the context of a prompt. For example, "My uncle's son is my <----->" would be answered with "cousin". dashermakefillin int dashermakefillin ( int, string prompt, string obj ) prompt obj The string of characters you will show to elicit a response. The string of characters the user is expected to enter. A 0 (zero) if command completed successfully, or a negative number indicating an error code (see Appendix A). Description: Fill-in-the-blank exercises with short, one-word or multi-word objects (rather than full-sentence objects) allow students to move swiftly through the material. This format also has the advantages of focusing the student's attention and reducing typing errors. Dasher supports two types of fill-in-the-blank exercises separate object and embedded object. With either type after calling dashermakefillin you can call dashergetfillinprompt to get back the altered prompt for display. You can call dashergetfillinobj to retrieve the altered object. You can also call dashergetfillinresponse to get a string that will be appropriate to display as a starting point for students. By default {} indicates the blank and the <-----> is used to display the blank. You can change these defaults with dashersetauthormarks and dashersetfillinblank. Creating a fill-in-the-blank item with a separate object: In the fill-in format with a separate object, students type just the correct object that completes the item. For example: prompt: My uncle's son is my {}. object: cousin After calling dashermakefillin dashergetfillin(prompt/object/response) would return: prompt: My uncle's son is my <----->. object: cousin response: (The response is an empty string.) Fill-in with separate object supports multiple blanks and alternate answer formats. Copyright James P. Pusack, Sue K. Otto and The University of Iowa 32

33 Creating a fill-in-the-blank item with an embedded object: In the fill-in format with an embedded object, students type just the correct object that completes the item in a blank embedded in the response, which is "preloaded" with the original prompt. For example: prompt: My uncle's son is my {}. object: {cousin} (Notice the braces surrounding cousin.) After calling dashermakefillin dashergetfillin(prompt/object/response) would return: prompt: My uncle's son is my <----->. object: My uncle's son is my cousin. response: My uncle's son is my. You can change the character used to indicate the fill-in characters by using dashersetmarkupcharacters. We recommend that when using this style item you do not show the prompt and constrain the student's typing to just the fill-in characters. Although you cannot use alternate answers in this format you can use more than one word within the blank and can use multiple blanks. You can also pad the object with spaces to mask the number of correct characters. The fill-in character is always considered a non-judged character so if students leave extra fill-in characters, dashermarkup will ignore them. For example: prompt: My uncle's son is my {}. object: {cousin } After calling dashermakefillin dashergetfillin(prompt/object/response) would return: prompt: My uncle's son is my <----->. object: My uncle's son is my cousin. response: My uncle's son is my. int returnvalue = WebService dashermakefillin (, prompt, obj); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 33

34 dashergetfillinprompt string dashergetfillinprompt ( int ) The prompt that has been created from your prior call to dashermakefillin. Returns an empty string if an invalid sessionid is supplied. Description: The author marks designating a fill in location are replaced by the fill-in-the-blank string. string prompt = WebService dashergetfillinprompt (); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 34

35 dashergetfillinobj string dashergetfillinobj ( int ) The object that has been created from your prior call to dashermakefillin. Returns an empty string if an invalid sessionid is supplied. Description: The author marks designating a fill in location are removed and the object is transformed so it can be used in a subsequent call to dashermarkup. string obj = WebService dashergetfillinobj (); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 35

36 dashergetfillinresponse string dashergetfillinresponse ( int ) The response that has been created from your prior call to dashermakefillin. Returns an empty string if an invalid sessionid is supplied. Description: A response is created that is appropriate to give users as a starting point when entering their response to this item. string response = WebService dashergetfillinresponse (); Copyright James P. Pusack, Sue K. Otto and The University of Iowa 36

37 Appendix A: 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 development. Error Codes All routines that return a numeric 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 do not have an expected return value, and will merely return 0 when there is no error, to indicate the routine completed successfully. (This is really a "success" code, but is included in the below table for completeness.) Code Occurs In Command Executed? 0 (Success) dashercheckitem, dasherdispose, dashermakefillin, dashersetauthormarks, dashersetcasematters, dashersetcriticallength, dashersetfillinblank, dashersetjudgewholewords, dashersetjudgedcharacters, dashersetmarkupcharactes, dashersetnonjudgedcharacters, Yes Explanation: Zero (0) returned for the listed routines merely indicates successful completion. Code Occurs In Command Executed? -1 (Invalid ) All routines where session ID is passed and an error code can be returned. No Explanation: The session ID passed was invalid. Either session ID was erroneous or the session has timed out. Code Occurs In Command Executed? -2 (Error occurred) All routines that can return an error code except dasherinit. No Explanation: An error has occurred as a result of parameters passed or the condition under which the routine was called. A call to dashermessage 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) All routines that can return an error code except dasherinit. Yes Explanation: A warning has occurred as a result of parameters passed or the condition under which the routine was called. A call to dashermessage inserted immediately after the call producing the error will return a string with more detail about the specific warning. Code Occurs In Command Executed? -4 (Invalid developerid) dasherinit No Explanation: An invalid developer ID has been passed. The command could not be executed and a session could not be returned. To be valid, a developer ID must exactly match the developer ID provided to you through the Dasher information & registration site (see section "Requirements for Using Dasher" earlier in this manual). Note that any leading or trailing space characters passed are ignored. Code Occurs In Command Executed? -5 (Database error) dasherinit No Explanation: An error has occurred, due to a problem with the Dasher database. Please contact the Dasher administrator. A session ID was not returned. Copyright James P. Pusack, Sue K. Otto and The University of Iowa 37

38 Code Occurs In Command Executed? -6 (Invalid interactionid) dasherinit No Explanation: An invalid interaction ID has been passed. The command could not be executed and a session could not be returned. Valid interaction IDs 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. Code Occurs In Command Executed? -7 (Invalid studentid) dasherinit No Explanation: An invalid student ID has been passed. The command could not be executed and a session could not be returned. Valid student IDs 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. Code Occurs In Command Executed? -10 (developerid not in database) dasherinit No Explanation: A developer ID 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 developer ID must exactly match the developer ID provided to you through the Dasher information & registration site (see section "Requirements for Using Dasher" earlier in this manual). Code Occurs In Command Executed? -11 (generated ID limit exceeded) dasherinit 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 Dasher generate the student ID and return a session ID. This limit of 100 is not in place for developer-supplied student IDs. Copyright James P. Pusack, Sue K. Otto and The University of Iowa 38

39 Error Messages A call to dashermessage immediately following another Dasher call will return a string containing any error messages generated by the previous call. Note that this is true only if a valid session ID the same one in effect during the previous call is passed. The following list of messages shows which method can generate the error that is returned by calling dashermessage. dashercheckitem Object has character[s] not declared as judged or non-judged. This object has no characters in the judged character set. The marks indicating an arrow-format alternate are not in pairs. An alternate object has a pattern flag but is missing the digit that must follow. A critical portion of the alternate is found elsewhere in the answer. The last alternate must not have a pattern flag. The marks indicating a blank are not in pairs. An object with an embedded fill-in must not contain alternates. Objects that use the slash format must end with a slash. Incorrect alternate format. Each alternate group must be closed with >. Incorrect alternate format. Each alternate group must have / to separate the alternates. Dasher was unable to check this item. dashermakefillin Dasher was unable to create this fill in. Run dashercheckitem on this item. dashermarkup Dasher was unable to markup this response. Run dashercheckitem on this item. dashersetauthormarks, dashersetmarkupcharacters The supplied value did not have the required number of characters. dashersetcriticallength The critical length value must be from 2 to 4 inclusive. dashermarkup, dashercheckitem, dashermakefillin, dashersetjudgedcharacters, dashersetnonjudgedcharacters Input(s) must not exceed {0} characters. ({0} is replaced by a specific number.) Copyright James P. Pusack, Sue K. Otto and The University of Iowa 39

40 Appendix B: Multiple Correct Objects Dasher is not designed to handle unpredictable or personalized student responses. Whenever possible, you should design the exercise to avoid ambiguities in the students minds about the response they are being asked to provide. Use the feature described here only when other approaches would prove too cumbersome, or when explicit directions would undercut the purpose of an exercise. (This may happen, in particular, in translation exercises. Avoid translation exercises from the target language into the student s native language, since the native speaker can always discover new ways to express the target language sentence.) Setting up an item with multiple correct objects is not simple, since it is quite possible that the student may make an error in the very segment of the object that contains alternate versions. Dasher is set up to "guess" which alternate object the student intends and then evaluate the wrong response based on this guess. To make this guess, Dasher examines the patterns in the student s response, which means that some guesses under complex conditions will fail to discover the student s intentions. These constraints also explain why using this feature is more complicated than using other aspects of Dasher. Proceed with caution. The multiple correct object facility provides two formats the slash format and the arrow format. Each of these formats is described in the following sections. Slash Format The simplest case of multiple objects occurs when there are two or more completely different possible objects. In a German vocabulary drill, the prompt might be "the car," for which German has two objects, "der Wagen" and "das Auto." For simple variants like this, it is best to use Dasher s "slash" format. The slash format is the simplest way to deal with multiple objects and should be used for vocabulary items and other cases when the alternates are substantially different. Creating multiple objects with the slash format The slash format is intended for multiple objects where there are two or more completely different possible responses. Each alternate within the master object contains the complete object (in contrast to the arrow format, where segments of the object can have alternates). This format is best used for vocabulary items and other cases where the alternates are substantially different. Type the alternate objects, including a slash (/ ) before and after each alternate. Be sure to end the object with a slash. The complete object, with its various alternates, is the "master" object. An item to translate "the car" in German might look like this. /der Wagen/das Auto/ Notice that the entire object is contained within each alternate. There is no limit to the number of alternates you can include, but the master object must contain no more than 500 characters. Dasher guesses which object the student intends by calculating which version has more characters in a row matching the student s response. If no match is found, Dasher uses the last version. Thus, you should put the most common or likely response last in the list of alternates. Arrow Format For sentence-length objects, you can use a more complex format, the "arrow" format. The arrow format allows you to build alternate versions of a master object and then mark the critical segments most likely to signal the student s intended version. For example, in German, the sentence: I have a car can be translated as either: Ich habe einen Wagen. or Ich habe ein Auto. Note that the ending on "ein" changes, as well as the noun. Copyright James P. Pusack, Sue K. Otto and The University of Iowa 40