paragraph.<< Command/TCL

paragraph.<<

Command paragraph.<< Command/TCL
Applicable release versions: AP 6.1
Category TCL (746)
Description gets user input or parameters in a paragraph.

The paragraph input function has many forms. All of them get input from one of several sources, and substitute that input in place of the original function on the paragraph line.

The first form of the paragraph input function, which begins with "c" followed by a number, indicates that the input function should be replaced by the nth parameter on the original TCL line executing the paragraph. The first parameter returns the paragraph name.

The next form, using the "i" indicator, is identical to the "C" form except that if the parameter is null, then the user will be prompted for the desired input.

To get input from a file, use the "f" indicator. If the item or file is not found, then the user will be prompted with the specified prompt.

To get input from the keyboard, use the last syntax. This has several portions:

a Normally, if a duplicate prompt appears twice in a paragraph, the user will NOT be prompted more than once for the input. Instead all further uses of the same prompt will remember the original input and return the result without user intervention. If the "a" option is used, then the user is "A"lways prompted even if the data is already present.

r This option causes the input statement to "R"epeat until the input is null. The final result will contain every previous input separated by spaces. This is useful for creating item lists.

After the options, the user may specify a direct cursor address or several pre-defined constants.

Finally, the input statement requires a prompt string followed by an optional mask. The mask has the same syntax as that used by the BASIC matches function.

If the user types "quit" at any paragraph input prompt, then the paragraph will terminate and return to TCL.
Syntax <<cnumber>>
<<inumber,prompt.text>>
<<f(filename,itemname{,attribute{,value}}),prompt.text>>
<<{a|r}{,@([x,y|bell|clr]),prompt.text{,mask}>>
Options
Example
paragraph
display File = <<i2,Enter File>>
list <<Enter File>> _
<<r,Items in <<Enter File>> (Return to terminate)>> a1 
a3 a3

  This paragraph will extract the file name from the second word of the 
original TCL statement.  If that parameter is not present, then the paragraph 
prompts for the name.  Next the line "File = {file.name}" is 
displayed.  After that, the user is prompted for "Items in {filename} 
(Return to terminate)>"  Note how the <<Enter File>> prompt 
is repeated, but the paragraph processor substitutes the existing file name 
since it has already been entered.  At the "Items..." prompt, the 
user may type several item names followed by the (return) key.  After 
terminating the input by entering a null entry, the paragraph will display a 
listing of those items in the desired file.
Purpose
Related paragraph.introduction
paragraph.>>
paragraph.if