The <<*AskOptions*>> command returns a 'fixed' result based on the position of the 'choice' in the list you provided. If you chose 'bananas' from the choices apples/banana/cherries, Pathagoras only knows that you chose the second item.
Sometimes this 'positional' approach will not work. Sometimes the actual value (and not its position in the list) is needed to control the result. If the answer to a question falls within a range of values, as opposed to being a specific value, you need a different approach. That's where the <<*AskValue*>> command comes into play.
Grades: An 'A' is a range from 90 to 100, a 'B' ranges from 80-89, etc. A score that deserves Honor Roll recognition is any score of 85 and above.
Let's assume a test score of 88. You conceivably could have several lists of 101 choices each (all tied together with a groupname so they change in tandem), one list representing the actual numeric score (e.g., 100/99/98/. . . ./90/89/88/ . . . /0), another 100 element list representing the letter grades by position (A/A/A/. . . . /A/B/B . . . ./F), and 100 choices representing whether a particular grade made the honor rolls (Honor roll/Honor roll/ . . . /Not honor roll/ . . . etc). But that borders on the absurd.
Enter the <<*AskValueInRange*>> command, Pathagoras 'Asks' for a specific value of 'something' (grade, quantity, score, etc.) at the top of the document. It will then analyze the response per a variety of 'ranges' that you provides elsewhere in the document. As with other <<*Ask*>> commands, Pathagoras requires you to provide a !groupname! to associate it with other elements in the document.
The AskValue method. Example #1
(You can copy and paste the above sample into your document and 'process' it.) (Note: in line 'c' there are 2 options. The 'no text' before the first slash after the close of the administrative text is a choice. Just a blank one.
When the user assigns a value in response to the <<*AskValueInRange*>> command, Pathagoras remembers its value and applies what it knows in one of two situations:
1.If an options block containing only the !groupname! (written like this: <<!groupname!>>) is located within the document, it will be directly replaced with the raw value. This is shown in line b. above.
2.When you have provided a 'full' <<*Options* . . .>> block that contains value 'ranges' within the administrative section of the block, Pathagoras will analyze the answer using those ranges and return the appropriate value. This is shown in lines b. and c. above.
Note (and this illustrates the very important distinction between AskValueInRange and AskOptions): The element count need not be the same within various member of the AskValueInRange group member. -- note that 5 options are provided in line b. above. Only 2 choices are provided in line c. (Note also, in line c, the result of the first choice -- the grade is between 0 and 84 -- is a 'blank'. There is no text between the asterisk that closes the administrative text and the first slash, meaning 'type nothing'. Therefore, no 'honor roll' award is presented.)
The AskValueInRange method. Example #2
(You can copy and paste the above sample into your document and 'process' it.)
The above is example provides a different situation where AskValueInRange might be used. It also illustrates that non-finite ranges can be used. Note the '>75' in both lines. You can use '>' and '<' and '<=' and '>=' (The order of the signs does not matter. So you could have '=>' as well.)
In the area of direct value replacement, you have to decide whether the value is best provided using the Instant Database or via the AskValue command.
When AskValueInRange is better than Variables:
•With AskValueInRange, the presumption is that the value will be analyzed in multiple locations in the document with varying sets of ranges. (This is not a requirement, but is the reason why the routine was written. You can use AskValueInRange to replace AskOptions, but the setup for AskOptions is quite a bit easier.
•Use AskValueInRange where there is no pressing need to save the value as part of an Instant Database record. You want to save the customers name, address, etc., so that you can use that information in letter after letter, but you may not need to record (at least for document assembly purposes) the specific grade or the amount of the purchase that leads to the generation of the document. (That data presumably is recorded elsewhere.)
Note the following structural requirements:
The <<*AskValueInRange*>> command, like all <<*Ask . . .>> commands, closes with a "*".
The comparison must be between a minimum of two sets of values. Those values can be a finite range (e.g., 0-75) or an non-finite range (e.g., >75; >=75 will also work).
Each 'range' option must have a corresponding 'return' option. So, in this example:
<<*Options*!Grade!0-89/90-100*Sorry, you did not make the honor roll/Congratulations! You have made the honor roll.>>
there are two ranges: '0-89' and '90-100'. The 'return' text is whatever appears after the "*" that closes the administrative section of the block.
Let's provide one more example. There is no sense in 'rubbing in' the fact that the 75 grade student did not make the honor roll. Perhaps it is best just to say nothing.
<<*Options*!Grade!0-89/90-100*/Congratulations! You have made the honor roll.>>
In the above example, "/Congratulations! You have made the honor roll" is now the return text. The slash, with no text preceding it, means it is a 'blank' choice. It returns 'nothing'.
Here is a psychological example, returning the IQ Classifications for the Wechsler Intelligence Scale for Children–Fifth Edition (WISC-V):
<<*Options*<69/70-79/80-89/90-109/110-119/120-129/>130*Extremely Low/Very Low/Low Average/Average/High Average/Very High/Extremely High>>
When a [Variable] is better:
•When the result is a defined value needed only for a direct replacement and need not be analyzed for use elsewhere in the document and it is imperative that you save the value in the client/customer's Instant Database information.
NOTE: <<*AskValueInRange*>> commands must be manually created in the AskTable. If you have structured an <<*Options*>> block in the body of the document that is being scanned which contains ranges of values, Pathagoras will create an <<*AskOptions*>> command at the top, with the ranges reflected as the alternative choices. Simply change <<*AskOptions*>> to <<*AskValueInRange*>> and either replace the alternative choices with a simple question or just close the block with a "*".