The paragraph is a macro language allowing execution of TCL statements, looping structures, data stacking, screen input and output, and branching.
A paragraph is an item stored in the current master dictionary whose attribute 1 contains the word paragraph. For compatibility with other vendors, PA and T are also accepted as paragraph indicators.
In its simplest incarnation, a paragraph is a list of TCL commands similar to a standard macro. However, paragraphs also allow other features which make it much more powerful.
Syntax
tcl.commands |
CAUTION |
For compatibility reasons, the syntax rules for this statement are actually a bit more loose than the way they are specified here. New programmers are encouraged to use the suggested syntax as much as possible. |
Paragraphs allow simple loops by starting a block of commands with the loop command and ending that block with the repeat command. The loop command indicates the beginning of a loop in a paragraph.
Syntax
loop tcl.commands repeat |
NOTE |
The loop statement does nothing by itself. It must be followed by a repeat statement to cause the looping effect. Such a loop continues indefinitely unless terminated by a branch structure. It is not possible to execute the TCL loop statement from within a paragraph. |
As in a macro, paragraphs can stack data by adding a second value after a command. Also, a separate line can display with the syntax:
data {data to stack} |
This works in a similar fashion to the BASIC data statement.
The data statement stacks the data string from within a paragraph.
Syntax
data string |
WARNING |
Quotation marks are included in the data, if present. |
It is possible to solicit input and display output in a paragraph. To do simple output, use the display statement with a string argument. To do simple input, embed the desired prompt within << and >> (double angle brackets). For example, the line display <<Enter name>> prompts Enter name> and then prints the name.
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 syntax for screen input and output:
<<cnumber>> <<inumber,prompt.text>> <<f(file.name,item.name{,attribute{,value}}),prompt.text>> <<{options}{,@([x,y|bell|clr])},prompt.text{,mask}>> |
To get input from the keyboard, use the last form. The parameters include:
cnumber |
c, followed by a number option, 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. |
|
inumber |
i, followed by a number, is identical to the c form, except that if the parameter is null, then the user is prompted for the desired input. |
|
f(file.name, item.name) |
Gets input from a file. If the item or file is not found, then the user is prompted with the specified prompt. |
|
[] |
Separates elements. |
|
| |
Specifies either/or. |
|
options |
a |
Prompts the user even if the data is already present. If a duplicate prompt displays twice in a paragraph, the user is not prompted more than once for the input. Instead, all further uses of the same prompt remembers the original input and returns the result without user intervention. |
r |
Causes the input statement to repeat (r) until the input is null. The final result contains 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 predefined 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.
Typing quit at any paragraph input prompt terminates the paragraph and returns to TCL.
Unlike standard macros, the parameters to the original TCL command line executing a paragraph are not directly passed to the first command. Instead, they are placed in a buffer for the paragraph programmer to access individually. The << place the user input or parameters in a paragraph. For example, to access the first parameter (word) in the original line (which is the name of the paragraph), use <<c1>>. To access the second parameter, use <<c2>>.
The syntax for parameter manipulation:
<<cnumber>> <<inumber,prompt.text>> |
The parameters include:
cnumber |
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. |
|
inumber |
i, followed by a number, is identical to the c form, except that if the parameter is null, then the user is prompted for the desired input. |
|
prompt.text |
Displays text that requires user input. |
|
For conditional branching, the if-then-go construct is used.
The if statement is a conditional branch statement in a paragraph or PROC.
Syntax
if {"|’}string1{"|’} [<|l|=|e|>|g] {"|’}string2{"|’} then go label if [constant|<<input.prompt>>] [conditional] [constant|<<input.prompt>>]then go label |
The parameters include:
input.prompt |
Ties in the screen input and output syntax:
|
|
conditional |
|
|
label |
An alphanumeric label that displays elsewhere in the paragraph. |
The if command compares the two string operators. If they are both numeric, then they are compared numerically. If either or both cannot be converted to a number, then they are compared alphabetically.
Between these two strings is a single-character conditional operator, which can be one of these:
< or l |
Less than |
= or e |
Equal to |
> or g |
Greater than |
If the condition evaluates to true, then the paragraph processor starts searching from the beginning of the paragraph for a label which matches the one after the go statement, but which must be followed by a colon and a space. When this label is found, execution of the paragraph continues on the line containing the label.
One of the string parameters in an if statement is usually an input substitution.
PA if <<Input a number between 1 and 10:>> > 5 then go greater display Less than or equal to 5 Go done greater: display Greater than 5 done: * There must be a space after the colon |
The example above asks the user for a number, and then prints a result based on the value of this number.
Labels are used as the target of if-then-go statements and consist of an alphanumeric label name, followed by a colon, and at least one space. Other paragraph commands can follow on the same line. The syntax for labels:
labels: {tcl.commands} |
For example:
if<<inputx>><3 then go less 3 less 3: displays something |
Any line beginning with an asterisk is assumed to be a comment. For example, *comment.
Any line ending with an underscore is merged with the succeeding line when processed by the paragraph processor.
NOTE |
Leading spaces on the next line are truncated. |
Example(s)
This paragraph extracts the file name from the second word of the original TCL statement. If the parameter is not present, then the paragraph prompts for the name. Next, the line File={file.name} displays. After that, the user is prompted for items in {file.name}(return to terminate)>.
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 pressing ENTER. After terminating the input by entering a null entry, the paragraph displays a listing of those items in the desired file.
paragraph display file = <<i2,enter file>> list <<enter file>> _ <<r,items in <<enter file>> (return to terminate)>> a1 a3 a3 |
This paragraph lists the default file of bp if no file is specified. When listing the file, it first prompts for the options.
paragraph * List a default file if not specified if <<c2>> = "" then go default list <<c2>> (<<Input options>> if 1 = 1 then go done default: list bp (<<Input options>> done: * Done with paragraph |
See Also