Basic request structure
SOUL statements are grouped together into requests. Requests can retrieve specific sets of records, operate on each record retrieved one-by-one or as a set, and display or save data from the retrieved records. A single request can perform one or more of these functions. Model 204 requests are processed as a unit.
The statements are read in and compiled, any diagnostic messages are displayed, and the request is executed if no errors have occurred.
General request format
The structure of User Language requests can vary, depending on the nature of the request.
However, there are some basic elements of the request structure that are common to all requests, including:
- Beginning and ending a request
- Input lines for statements
- Spaces between words
- Using abbreviations
- Using statement labels
Example
The following simple request prints the number of Ford automobiles in a VEHICLES file:
BEGIN FORDS: FIND ALL RECORDS FOR WHICH MAKE = FORD END FIND NO.OF.FORDS: COUNT RECORDS IN FORDS PRINT 'NUMBER OF FORDS = ' - WITH COUNT IN NO.OF.FORDS END
The resulting output is:
NUMBER OF FORDS = 255
The previous request can be written another way using fewer lines of code:
BEGIN PRINT 'NUMBER OF FORDS = ' ... FPC MAKE = FORD END FIND END
The result is the same:
NUMBER OF FORDS = 255
The two previous examples illustrate the features of User Language described in the following sections.
Abbreviations
Some statements and commands can be abbreviated. In this case, B is an abbreviation for the BEGIN command, and FPC is an abbreviation for the FIND AND PRINT COUNT statement. Reserved words and characters lists allowed abbreviations for User Language statements and certain Model 204 commands.
Continuation statements
In some cases, a User Language statement combines the functionality of two or more other statements. In this example, the FPC statement combines the functions of the FIND ALL RECORDS, PRINT, and COUNT statements.
Beginning and ending a request
An input line that contains only the system control command BEGIN starts a request. The User Language statements that make up the request follow.
The request is ended by an END statement. The END statement, if it returns the user to include level 0 or terminal command level, also COMMITs any active update transaction. An END statement in a request that is part of a multiple-request procedure, does not necessarily COMMIT an active update transaction; COMMIT only occurs at the outermost END of a multiple-request procedure.
Input lines for statements
Each SOUL statement begins a new input line.
Statement entry can begin in any column. When a statement is too long to fit on one line, a special symbol is used to continue the statement on the next line. See Use of hyphens for more information on line continuation.
Indentation is used throughout the SOUL documentation to make the structure of a request more obvious to the reader. Indentation is not a requirement of SOUL.
Spaces between words
Extra spaces between words are ignored.
Statement labels
Statement labels provide a method for naming User Language statements. Several User Language statements allow references to the statement labels of other statements.
Statement labels
As the examples in General request format illustrate, statements are sometimes labeled. The use of labels allows you to assign a meaningful name to any statement or group of statements.
Example of a statement label
FIND.FORDS: FIND ALL RECORDS FOR WHICH MAKE = FORD
When to use labels
Any statement can be labeled; however, certain statements must be labeled.
A statement must be labeled if it is referred to by later statements within the request. For example, the COUNT statement in General request format was labeled because it was subsequently referred to by the PRINT statement. Statements requiring a label are identified throughout this manual. In addition, a listing of statements requiring a label is given on Statements that must be labeled.
Rules for statement labels
The general rules for labeling statements are:
- If a statement is labeled, the label must be the first word on the line. The label can start in any column up to but not including the column specified by the INCCC parameter.
- A statement label should not be a User Language keyword. Model 204 interprets a statement label which is a keyword as the keyword itself, not as a statement label, if that keyword makes syntactic sense where the statement label is referenced.
- The label must begin with a letter (a-z, A-Z) which can be followed by one or more occurrences of a letter, digit (0-9), period (.), or underscore (_). The label can be a maximum of 254 characters.
- The label must end with a colon and be followed by a space.
- Within a request, statement labels must be unique.
Statement label references
Labels allow statements to refer to other User Language statements (for example, a set of records that has been retrieved with a FIND statement).
A label reference must be coded exactly as the label, including upper- and lower-case lettering. However, the label reference must omit the colon.
The following request illustrates a statement label reference:
BEGIN FORDS: FIND ALL RECORDS FOR WHICH MAKE = FORD END FIND NO.OF.FORDS: COUNT RECORDS IN FORDS PRINT 'NUMBER OF FORDS ' - WITH COUNT IN NO.OF.FORDS END
In this example, the COUNT statement uses the FORDS label to refer to the results of the FIND statement. Similarly, the PRINT statement uses the NO.OF.FORDS label to refer to the result of the COUNT statement.
Statement numbers
For compatibility with older Model 204 releases, statement numbers can be used to label and refer to statements.
However, Rocket Technical Support strongly recommends using statement labels instead of statement numbers. Refer to Obsolete features for the rules for numbering statements.
User language blocks
Some statements in User Language introduce a series of nested statements. Other statements introduce a sequence of multiline conditions. A series of nested statements or multiline conditions is called a block.
Note: The term "block" is used in a different sense in relation to the use of User Language images (refer to Images).
Ending a block
In User Language, you must signal Model 204 that the block has ended. The ways in which you can end a block are summarized as follows. Statements that require a block end are identified throughout the manual. Additionally, Statement block ends contains a listing of statements requiring a block end.
Block end statement
Statements that begin a block are ended by using a block end statement. The general format of a block end statement is shown below:
END {statement type} [label]
where the optional label must match the label of the block that is being ended.
In this example, an END FIND statement is used to end a FIND statement (which requires a block end):
FIND.FORDS: FIND ALL RECORDS FOR WHICH MAKE = FORD COLOR = BLUE END FIND
Another label
Statements that begin a sequence of multiline conditions can be ended simply by labeling the next statement. In this example, the label of the next statement (PRINT.MODEL) ends the FIND statement:
FIND.FORDS: FIND ALL RECORDS FOR WHICH MAKE = FORD COLOR = BLUE PRINT.MODEL: FOR EACH RECORD IN FIND.FORDS . . .
END BLOCK statement
Statements that begin a series of nested statements can be ended by using the END BLOCK statement. END BLOCK closes all open blocks and returns the nesting level to the level of the label that is being ended. END BLOCK is particularly useful when several types of block statements are nested within each other.
The END BLOCK statement has this format:
END BLOCK label
In this example, the FOR and IF statements both require a block end statement. However, rather than specify a separate block end statement for each one, the user has used the END BLOCK statement to end both statements.
FIND.FORDS: FIND ALL RECORDS FOR WHICH MAKE = FORD END FIND PRINT.INFO: FOR EACH RECORD IN FIND.FORDS IF YEAR = 80 THEN PRINT MODEL AND COLOR END BLOCK PRINT.INFO END
In addition to the ways listed above, a block can be ended by other forms of the END statement (END, END MORE, END USE, END NORUN). These forms end the request, thereby automatically ending all statements within the request.
Input line continuation
Use of hyphens
Some statements cannot fit on a single line and therefore must be continued. In such cases, use a hyphen as the last character on the line to indicate that the statement continues on the next line:
PRINT FULLNAME AND MARITAL STATUS - AND SEX
The hyphen acts as a continuation symbol, provided that no other characters follow it.
Do not use a hyphen after the first line of a FIND statement in the form:
FIND ALL RECORDS FOR WHICH
See Specify retrieval criteria on one logical line for information about line continuation with FR WHERE statements.
Alternate line continuation method
A statement also can be continued by inserting any nonblank character directly following the last legal column of the line. However, this form of continuation generally is not recommended in User Language because it is less flexible than the hyphen. The continuation column number is controlled by a user parameter, INCCC.
Do not insert blank lines or comment lines
You should not use blank lines or comment lines between continued lines. This example illustrates three problems that can occur if you use blank lines or comment lines between continued lines (for example, if you wanted to double-space your code or note a reason for continuing the line).
B %A = 'AAA- BBB' PRINT %A IF $SETG('A','B') OR - $SETG('B','C') THEN PRINT 'ERROR' IF $SETG('A','B') OR - * THIS IS A COMMENT LINE $SETG('B','C') THEN PRINT 'ERROR' END
First, when you print %A, the system displays "AAA;BBB"; Model 204 inserts a semicolon to represent the blank line.
The second problem is that the second $SETG statement is rejected with an "INVALID STATEMENT" message. To correct these two problems, add a hyphen to each blank line following the continued line.
The third problem is similar to the second, except that there is a comment line (instead of a blank line) between the two parts of the continued line. In this case, both the comment line and the second $SETG statement are rejected with error messages. Adding a hyphen to the end of the comment line does not remedy this problem. See Putting comments into code for more on comment lines.
This example illustrates proper coding:
BEGIN %A = 'AAA- - BBB' PRINT %A IF $SETG('A','B') OR - - $SETG('B','C') THEN PRINT 'ERROR' END
Syntax checking and line continuation
The following expression is invalid because the first line (IF %X. . .) needs a continuation hyphen:
IF %X = %Y * %Z THEN
Invalid expressions are recognized as syntax errors and produce the following message:
M204.0298: INVALID OPTION: cccc
where cccc is the program text that was in error.
Also, the lack of a continuation hyphen following an "AND" or an "OR" within a conditional "IF" statement:
IF FIELD1 = A AND FIELD2 = B AND FIELD3 = C THEN PRINT X
results in a compiler error.
The proper syntax for the above statement is:
IF FIELD1 = A AND - FIELD2 = B AND - FIELD3 = C THEN PRINT X
Putting comments into code
You can annotate requests by inserting comments between statements. Model 204 supports comments on individual lines and in blocks.
| Type of comment | How to format | Recommendations |
|---|---|---|
| Individual lines | An asterisk, optionally preceded by a statement label, begins an individual line comment. Each line of a multiline comment must begin with an asterisk. |
A comment line should not:
|
| Block comments |
Signified by the /? and ?/ default block comments delimiter pair. You can reset the comment delimiter pair using the CCAIN parameters, COMSTART and COMEND. The default values are /? and ?/, respectively. |
Technical Support recommends using the default values. However, if you want to reset the delimiters, avoid reserved characters and test thoroughly. |
Usage
Using caution with /* and */ as the delimiter pair
If you reset the comment delimiter pair to COMSTART= /* and COMEND=*/, keep in mind that if you use the COMEND parameter at the beginning of a line, */ is evaluated as an individual line comment.
The following program remains in comment mode: the A character is not printed. If the first characters detected after leading white spaces are */, the entire line is considered an old-style comment.
BEGIN /* begin and end a comment */ PRINT 'A' END
The following program prints the A character, because an asterisk is not the first character on the line.
BEGIN /* begin and end a comment x */ PRINT 'A' END
Handling dummy strings in block comments
By default, dummy strings (??) are not recognized within block comments. However, if you enable dummy strings, you can activate them within the block comments by resetting the PROMPT parameter with the X'02' bit on.
You can enter /? multiple times within a comment block, but to exit comment mode you must enter an equal number of ?/.
If a /? or ?/ is enclosed within quotes ('/?' or '?/') neither is considered a comment delimiter.
If a /? is found on a line and no corresponding ?/ is found, the comment continues onto additional lines; the line itself is considered continued. When the comment lines end, each word of the new line becomes part of the original line, regarded as a comment block. Comment delimiter pairs enable you to continue a line without the use of a dash.
Examples
The following program prints BEFOREAFTER, although BEFORE and AFTER are separated by a block of comments:
BEGIN PRINT 'BEFORE' /? THIS BEGINS COMMENT1 THIS LINE REMAINS COMMENT1 EVEN WITH '?/' IMBEDDED AND COMMENT1 ENDS HERE ?/ 'AFTER' /? THIS IS COMMENT2 ?/ END BEFOREAFTER
The following program prints A followed by BC, although they are separated by a block of comments. These comments illustrate that the old style comments lines (* as first non-label character) continue to function; you can use them along with the comment delimiter pairs:
BEGIN PRINT 'A' /? THIS BEGINS AND ENDS A COMMENT ?/ LABEL: * THIS IS MODEL 204 OLD-STYLE COMMENT LINE ** AND SO IS THIS ONE PRINT 'B' /? MORE COMMENTS BEGIN HERE * ?/ /? * AND CONTINUE AND CONTINUE (STILL INSIDE COMMENT DELIMITERS) AND THEY FINALLY END HERE ?/ 'C' END A BC
For example, the following command prints the values of the LVTBL and LQTBL parameters, to illustrate that you can use the comments delimiter pair on command statements:
VIEW /? THIS IS COMMENT1 AND IT CONTINUES /? AND IT CONTINUES ?/ AND IT STILL CONTINUES (ONLY 1 PAIR CLOSED) AND COMMENT1 ENDS HERE ?/ LVTBL, /? CONTINUE LINE WITH COMMENT2 AND END COMMENT2 ?/ LQTBL /? FINALLY WE ARE FINISHED ?/ LVTBL 3100 LENGTH OF VTBL LQTBL 8490 LENGTH OF QTBL
Compilation termination and request cancellation
Stopping compilation: the End statement
The syntax of the End statment is:
End [NoRun] [More [Use]]
If you are entering a request and want to stop after compilation and before evaluation, you can enter this statement:
end norun
End NoRun terminates the request and returns you to command level. The request is stored as temporary procedure 0. For more information about temporary procedures, refer to Procedures.
End More terminates the request but allows continuation of the request with the More command. Specifying Use in addition to More keeps any USE dataset in effect open for the request continuation.
Cancelling a request
The *CANCEL command or the attention key can be used to terminate certain types of processing. The key used as the attention key depends upon the terminal or access method being used. Refer to the Category:Terminal processing and support page to locate a detailed description of the attention key used for each terminal or access method.
These methods of cancellation are most helpful to the user who is receiving unexpected responses or prompts from Model 204. When a request is being entered, the cancellation has the same effect as End NoRun. Control is returned to command level.
Additional information: