Basic request structure: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(rewritten to delete reference to old version)
 
(21 intermediate revisions by 4 users not shown)
Line 1: Line 1:
===Overview===
<p>
<p>User Language 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. <var class="product">Model&nbsp;204</var> requests are processed as a unit.    </p>
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. <var class="product">Model&nbsp;204</var> requests are processed as a unit.    </p>
<p>The statements are read in and compiled, any diagnostic messages are displayed, and the request is executed if no errors have occurred.</p>
<p>
===General request format===
The statements are read in and compiled, any diagnostic messages are displayed, and the request is executed if no errors have occurred.</p>
<p>The structure of User Language requests can vary, depending on the nature of the request. </p>
__TOC__
<p>However, there are some basic elements of the request structure that are common to all requests, including:</p>
==General request format==
<p>
The structure of User Language requests can vary, depending on the nature of the request. </p>
<p>
However, there are some basic elements of the request structure that are common to all requests, including:</p>
<ul>
<ul>
<li>Beginning and ending a request</li>
<li>Beginning and ending a request</li>
Line 13: Line 19:
</ul>
</ul>
<b>Example</b>
<b>Example</b>
<p>The following simple request prints the number of Ford automobiles in a VEHICLES file:        </p>
<p>
The following simple request prints the number of Ford automobiles in a VEHICLES file:        </p>
<p class="code">BEGIN
<p class="code">BEGIN
FORDS:      FIND ALL RECORDS FOR WHICH
FORDS:      FIND ALL RECORDS FOR WHICH
Line 21: Line 28:
             PRINT 'NUMBER OF FORDS = ' -
             PRINT 'NUMBER OF FORDS = ' -
             WITH COUNT IN NO.OF.FORDS
             WITH COUNT IN NO.OF.FORDS
END  
END
</p>
</p>
<p>The resulting output is:</p>
<p>
<p class="code">NUMBER OF FORDS = 255  
The resulting output is:</p>
<p class="code">NUMBER OF FORDS = 255
</p>
</p>
<p>The previous request can be written another way using fewer lines of code: </p>
<p>
The previous request can be written another way using fewer lines of code: </p>
<p class="code">BEGIN
<p class="code">BEGIN
   PRINT 'NUMBER OF FORDS = ' ...
   PRINT 'NUMBER OF FORDS = ' ...
Line 33: Line 42:
END
END
</p>
</p>
<p>The result is the same:</p>
<p>
<p class="code">NUMBER OF FORDS = 255  
The result is the same:</p>
<p class="code">NUMBER OF FORDS = 255
</p>
</p>
<p>The two previous examples illustrate the features of User Language described in the following sections.</p>
<p>
<b>Abbreviations</b>
The two previous examples illustrate the features of User Language described in the following sections.</p>
<p>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#Reserved Words and Characters|Reserved Words and Characters]] lists allowed abbreviations for User Language statements and certain <var class="product">Model&nbsp;204</var> commands.</p>
 
<b>Continuation statements</b>
===Abbreviations===
<p>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.</p>
<p>
<b>Beginning and ending a request</b>
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 <var class="product">Model&nbsp;204</var> commands.</p>
<p>An input line that contains only the system control command BEGIN starts a request. The User Language statements that make up the request follow.  </p>
 
<p>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.  </p>
===Continuation statements===
<b>Input lines for statements</b>
<p>
<p>Each User Language statement begins a new input line.</p>
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.</p>
<p>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|Use of hyphens]] for more information on line continuation.</p>
 
<p>Indentation is used throughout this manual to make the structure of a request more obvious to the reader. Indentation is not a requirement of User Language.  </p>
===Beginning and ending a request===
<b>Spaces between words</b>
<p>
<p>Extra spaces between words are ignored.  </p>
An input line that contains only the system control command BEGIN starts a request. The User Language statements that make up the request follow.  </p>
<b>Statement labels</b>
<p>
<p>Statement labels provide a method for naming User Language statements. Several User Language statements allow references to the statement labels of other statements.</p>
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.  </p>
 
===Input lines for statements===
<p>
Each SOUL statement begins a new input line.</p>
<p>
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|Use of hyphens]] for more information on line continuation.</p>
<p>
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.  </p>
 
===Spaces between words===
<p>
Extra spaces between words are ignored.  </p>


===Statement labels===
===Statement labels===
<p>As the examples in [[#General request format|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. </p>
<p>
====Example of a statement label====
Statement labels provide a method for naming User Language statements. Several User Language statements allow references to the statement labels of other statements.</p>
<p class="code">FIND.FORDS: FIND ALL RECORDS FOR WHICH  
 
                 MAKE = FORD  
==Statement labels==
<p>
As the examples in [[#General request format|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. </p>
===Example of a statement label===
<p class="code">FIND.FORDS: FIND ALL RECORDS FOR WHICH
                 MAKE = FORD
</p>
</p>
====When to use labels====
<p>Any statement can be labeled; however, certain statements must be labeled. </p>
===When to use labels===
<p>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|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 [[Request Composition Rules#Statements that must be labeled|Statements that must be labeled]].</p>
<p>
====Rules for statement labels====
Any statement can be labeled; however, certain statements must be labeled. </p>
<p>The general rules for labeling statements are:</p>
<p>
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|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 [[Request composition rules#Statements that must be labeled|Statements that must be labeled]].</p>
===Rules for statement labels===
<p>
The general rules for labeling statements are:</p>
<ul>
<ul>
<li>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. Refer to the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual for more information about the INCCC parameter.</li>
<li>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 <var>[[INCCC parameter|INCCC]]</var> parameter.
</li>
</li>
<li>A statement label should not be a User Language keyword. <var class="product">Model&nbsp;204</var> 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.</li>
<li>A statement label should not be a User Language keyword. <var class="product">Model&nbsp;204</var> 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.</li>
Line 76: Line 109:
</li>
</li>
</ul>
</ul>
====Statement label references====
<p>Labels allow statements to refer to other User Language statements (for example, a set of records that has been retrieved with a FIND statement). </p>
===Statement label references===
<p>A label reference must be coded exactly as the label, including upper- and lower-case lettering. However, the label reference must omit the colon.    </p>
<p>
<p>The following request illustrates a statement label reference:</p>
Labels allow statements to refer to other User Language statements (for example, a set of records that has been retrieved with a FIND statement). </p>
<p>
A label reference must be coded exactly as the label, including upper- and lower-case lettering. However, the label reference must omit the colon.    </p>
<p>
The following request illustrates a statement label reference:</p>
<p class="code">BEGIN
<p class="code">BEGIN
FORDS:      FIND ALL RECORDS FOR WHICH
FORDS:      FIND ALL RECORDS FOR WHICH
Line 87: Line 124:
             PRINT 'NUMBER OF FORDS ' -
             PRINT 'NUMBER OF FORDS ' -
                 WITH COUNT IN NO.OF.FORDS
                 WITH COUNT IN NO.OF.FORDS
END  
END
</p>
</p>
<p>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.      </p>
<p>
====Statement numbers====
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.      </p>
<p>For compatibility with older <var class="product">Model&nbsp;204</var> releases, statement numbers can be used to label and refer to statements. </p>
<p>However, Rocket Technical Support strongly recommends using statement labels instead of statement numbers. Refer to [[Obsolete Features#Obsolete Features|Obsolete Features]] for the rules for numbering statements.    </p>
===Statement numbers===
<p>
For compatibility with older <var class="product">Model&nbsp;204</var> releases, statement numbers can be used to label and refer to statements. </p>
<p>
However, [[Contacting Rocket Software Technical Support|Rocket Technical Support]] strongly recommends using statement labels instead of statement numbers. Refer to [[Obsolete features]] for the rules for numbering statements.    </p>


===User language blocks===
==User language blocks==
<p>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 <i>block</i>. </p>
<p>
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 <i>block</i>. </p>
<p class="note"><b>Note:</b> The term "block" is used in a different sense in relation to the use of User Language images (refer to [[Images#Images|Images]]).</p>
<p class="note"><b>Note:</b> The term "block" is used in a different sense in relation to the use of User Language images (refer to [[Images#Images|Images]]).</p>
====Ending a block====
<p>In User Language, you must signal <var class="product">Model&nbsp;204</var> 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, [[Request Composition Rules#Statement block ends|Statement block ends]] contains a listing of statements requiring a block end.</p>
===Ending a block===
<b>Block end statement</b>
<p>
<p>Statements that begin a block are ended by using a block end statement. The general format of a block end statement is shown below:      </p>
In User Language, you must signal <var class="product">Model&nbsp;204</var> 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, [[Request composition rules#Statement block ends|Statement block ends]] contains a listing of statements requiring a block end.</p>
<p class="syntax">END {<span class="term">statement type</span>} [<span class="term">label</span>]  
 
====Block end statement====
<p>
Statements that begin a block are ended by using a block end statement. The general format of a block end statement is shown below:      </p>
<p class="syntax">END {<span class="term">statement type</span>} [<span class="term">label</span>]
</p>
</p>
<p>where the optional <i>label</i> must match the label of the block that is being ended.</p>
<p>
<p>In this example, an END FIND statement is used to end a FIND statement (which requires a block end):</p>
where the optional <i>label</i> must match the label of the block that is being ended.</p>
<p>
In this example, an END FIND statement is used to end a FIND statement (which requires a block end):</p>
<p class="code">FIND.FORDS: FIND ALL RECORDS FOR WHICH
<p class="code">FIND.FORDS: FIND ALL RECORDS FOR WHICH
               MAKE = FORD
               MAKE = FORD
               COLOR = BLUE
               COLOR = BLUE
             END FIND  
             END FIND
</p>
</p>
<b>Another label</b>
 
<p>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:</p>
====Another label====
<p>
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:</p>
<p class="code">FIND.FORDS:  FIND ALL RECORDS FOR WHICH
<p class="code">FIND.FORDS:  FIND ALL RECORDS FOR WHICH
                 MAKE = FORD
                 MAKE = FORD
Line 118: Line 168:
                   .
                   .
                   .
                   .
                   .  
                   .
</p>
</p>
<b>END BLOCK statement</b>
 
<p>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.    </p>
====END BLOCK statement====
<p>The END BLOCK statement has this format:</p>
<p>
<p class="code">END BLOCK <span class="term">label</span>  
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.    </p>
<p>
The END BLOCK statement has this format:</p>
<p class="code">END BLOCK <span class="term">label</span>
</p>
</p>
<p>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.</p>
<p>
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.</p>
<p class="code">FIND.FORDS: FIND ALL RECORDS FOR WHICH
<p class="code">FIND.FORDS: FIND ALL RECORDS FOR WHICH
                 MAKE = FORD
                 MAKE = FORD
Line 133: Line 187:
                     PRINT MODEL AND COLOR
                     PRINT MODEL AND COLOR
                 END BLOCK PRINT.INFO
                 END BLOCK PRINT.INFO
END  
END
</p>
</p>
<p>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.        </p>
<p>
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.        </p>


===Input line continuation===
==Input line continuation==
====Use of hyphens====
<p>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:            </p>
===Use of hyphens===
<p>
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:            </p>
<p class="code">PRINT FULLNAME AND MARITAL STATUS -
<p class="code">PRINT FULLNAME AND MARITAL STATUS -
     AND SEX  
     AND SEX
</p>
</p>
<p>The hyphen acts as a continuation symbol, provided that no other characters follow it.</p>
<p>
<p>Do not use a hyphen after the first line of a FIND statement in the form:</p>
The hyphen acts as a continuation symbol, provided that no other characters follow it.</p>
<p>
Do not use a hyphen after the first line of a FIND statement in the form:</p>
<p class="code">FIND ALL RECORDS FOR WHICH
<p class="code">FIND ALL RECORDS FOR WHICH
</p>
</p>
<p>See [[Record Loops#Specify retrieval criteria on one logical line|Specify retrieval criteria on one logical line]] for information about line continuation with FR WHERE statements.</p>
<p>
====Alternate line continuation method====
See [[Record loops#Specify retrieval criteria on one logical line|Specify retrieval criteria on one logical line]] for information about line continuation with FR WHERE statements.</p>
<p>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, which is set as described in the <var class="book">Rocket Model&nbsp;204 Parameter and Command Reference Manual</var>.  </p>
===Alternate line continuation method===
<p>
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, <var>[[INCCC parameter|INCCC]]</var>.  </p>


====Do not insert blank lines or comment lines====
===Do not insert blank lines or comment lines===
<p>You should <b>not</b> 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).</p>
<p>
You should <b>not</b> 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).</p>
<p class="code">B
<p class="code">B
%A = 'AAA-
%A = 'AAA-
 
BBB'
BBB'
PRINT %A
PRINT %A
IF $SETG('A','B') OR -
IF $SETG('A','B') OR -
 
   $SETG('B','C') THEN
   $SETG('B','C') THEN
   PRINT 'ERROR'
   PRINT 'ERROR'
 
IF $SETG('A','B') OR -
IF $SETG('A','B') OR -
   * THIS IS A COMMENT LINE
   * THIS IS A COMMENT LINE
   $SETG('B','C') THEN
   $SETG('B','C') THEN
   PRINT 'ERROR'
   PRINT 'ERROR'
END    
END
</p>
</p>
<p>First, when you print %A, the system displays "AAA;BBB"; <var class="product">Model&nbsp;204</var> inserts a semicolon to represent the blank line. </p>
<p>
<p>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. </p>
First, when you print %A, the system displays "AAA;BBB"; <var class="product">Model&nbsp;204</var> inserts a semicolon to represent the blank line. </p>
<p>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 <b>not</b> remedy this problem. See [[#Putting comments into code|Putting comments into code]] for more on comment lines.</p>
<p>
<p>This example illustrates proper coding: </p>
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. </p>
<p>
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 <b>not</b> remedy this problem. See [[#Putting comments into code|Putting comments into code]] for more on comment lines.</p>
<p>
This example illustrates proper coding: </p>
<p class="code">BEGIN
<p class="code">BEGIN
%A = 'AAA-
%A = 'AAA-
Line 182: Line 249:
   $SETG('B','C') THEN
   $SETG('B','C') THEN
   PRINT 'ERROR'
   PRINT 'ERROR'
END    
END
</p>
</p>
 
====Syntax checking and line continuation====
===Syntax checking and line continuation===
<p>The following expression is invalid because the first line (IF %X. . .) needs a continuation hyphen:</p>
<p>
The following expression is invalid because the first line (IF %X. . .) needs a continuation hyphen:</p>
<p class="code">IF %X = %Y *
<p class="code">IF %X = %Y *
   %Z THEN  
   %Z THEN
</p>
</p>
<p>Invalid expressions are recognized as syntax errors and produce the following message:</p>
<p>
Invalid expressions are recognized as syntax errors and produce the following message:</p>
<p class="syntax">M204.0298: INVALID OPTION: <var class="term">cccc</var>
<p class="syntax">M204.0298: INVALID OPTION: <var class="term">cccc</var>
</p>
</p>
<p>where <i>cccc</i> is the program text that was in error.</p>
<p>
<p>Also, the lack of a continuation hyphen following an "AND" or an "OR" within a conditional "IF" statement:</p>
where <i>cccc</i> is the program text that was in error.</p>
<p>
Also, the lack of a continuation hyphen following an "AND" or an "OR" within a conditional "IF" statement:</p>
<p class="code">IF FIELD1 = A AND
<p class="code">IF FIELD1 = A AND
   FIELD2 = B AND
   FIELD2 = B AND
Line 200: Line 271:
       PRINT X
       PRINT X
</p>
</p>
<p>results in a compiler error. </p>
<p>
<p>The proper syntax for the above statement is:</p>
results in a compiler error. </p>
<p>
The proper syntax for the above statement is:</p>
<p class="code">IF FIELD1 = A AND -
<p class="code">IF FIELD1 = A AND -
   FIELD2 = B AND -
   FIELD2 = B AND -
   FIELD3 = C THEN
   FIELD3 = C THEN
       PRINT X  
       PRINT X
</p>
</p>
 
 
===Putting comments into code===
==Putting comments into code==
<p>You can annotate requests by inserting comments between statements. <var class="product">Model&nbsp;204</var> supports comments on individual lines and in blocks.</p>
<p>
You can annotate requests by inserting comments between statements. <var class="product">Model&nbsp;204</var> supports comments on individual lines and in blocks.</p>
<table>
<table>
<tr class="head">
<tr class="head">
<th>Type of  
<th>Type of
comment </th>
comment </th>
<th>
<th>
Line 223: Line 297:
<td>An asterisk, optionally preceded by a statement label, begins an individual line comment. Each line of a multiline comment must begin with an asterisk.</td>
<td>An asterisk, optionally preceded by a statement label, begins an individual line comment. Each line of a multiline comment must begin with an asterisk.</td>
<td>
<td>
<p>A comment line should not:</p>
<p>
<p>Consist of an asterisk followed by a line of hyphens because the final hyphen is interpreted as a continuation character. </p>
A comment line should not:</p>
<p>Contain ??, ?$, or ?&amp; because these strings are interpreted as dummy string prompts. Refer to [[Procedures#Procedures|Procedures]] for more information about dummy strings.    </p>
<ul>
<li>Consist of an asterisk followed by a line of hyphens because the final hyphen is interpreted as a continuation character. </li>
<li>Contain ??, ?$, or ?&amp; because these strings are interpreted as dummy string prompts. Refer to [[Procedures#Procedures|Procedures]] for more information about dummy strings.    </li>
</ul>
</td>
</td>
</tr>
</tr>
Line 231: Line 308:
<td>Block comments </td>
<td>Block comments </td>
<td>
<td>
<p>Signified by the /? and ?/ default block comments delimiter pair. </p>
<p>
<p>You can reset the comment delimiter pair using the CCAIN parameters, COMSTART and COMEND. The default values are /? and ?/, respectively. </p>
Signified by the /? and ?/ default block comments delimiter pair. </p>
<p>
You can reset the comment delimiter pair using the CCAIN parameters, COMSTART and COMEND. The default values are /? and ?/, respectively. </p>
</td>
</td>
<td>Technical Support recommends using the default values. However, if you want to reset the delimiters avoid reserved characters and test thoroughly.</td>
<td>Technical Support recommends using the default values. However, if you want to reset the delimiters, avoid reserved characters and test thoroughly.</td>
</tr>
</tr>
</table>
</table>
<b>Usage</b>
 
<b>Using caution with /* and */ as the delimiter pair</b>
===Usage===
<p>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. </p>
====Using caution with /* and */ as the delimiter pair====
<p>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.</p>
<p>
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. </p>
<p>
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.</p>
<p class="code">BEGIN
<p class="code">BEGIN
/* begin and end a comment
/* begin and end a comment
Line 246: Line 328:
END
END
</p>
</p>
<p>The following program prints the A character, because an asterisk is not the first character on the line.</p>
<p>
The following program prints the A character, because an asterisk is not the first character on the line.</p>
<p class="code">BEGIN
<p class="code">BEGIN
/* begin and end a comment
/* begin and end a comment
Line 252: Line 335:
END
END
</p>
</p>
<b>Handling dummy strings in block comments</b>
 
<p>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. Dummy strings within individual line comments continue to function as in releases prior to V4R2.0. </p>
====Handling dummy strings in block comments====
<p>You can enter /? multiple times within a comment block, but to exit comment mode you must enter an equal number of ?/. </p>
<p>
<p>If a /? or ?/ is enclosed within quotes--'/?' or '?/'--neither is considered a comment delimiter. </p>
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.</p>
<p>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 are a new way to continue a line without the use of a dash. </p>
<p>
You can enter /? multiple times within a comment block, but to exit comment mode you must enter an equal number of ?/. </p>
<p>
If a /? or ?/ is enclosed within quotes ('/?' or '?/') neither is considered a comment delimiter. </p>
<p>
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. </p>
<b>Examples</b>
<b>Examples</b>
<p>The following program prints BEFOREAFTER, although BEFORE and AFTER are separated by a block of comments:</p>
<p>
The following program prints BEFOREAFTER, although BEFORE and AFTER are separated by a block of comments:</p>
<p class="code">BEGIN
<p class="code">BEGIN
   PRINT 'BEFORE' /? THIS BEGINS COMMENT1
   PRINT 'BEFORE' /? THIS BEGINS COMMENT1
                     THIS LINE REMAINS COMMENT1  
                     THIS LINE REMAINS COMMENT1
                     EVEN WITH '?/' IMBEDDED AND
                     EVEN WITH '?/' IMBEDDED AND
     COMMENT1 ENDS HERE ?/  'AFTER'  /? THIS IS COMMENT2 ?/
     COMMENT1 ENDS HERE ?/  'AFTER'  /? THIS IS COMMENT2 ?/
END
END
 
BEFOREAFTER
BEFOREAFTER
</p>
</p>
<p>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 new comment delimiter pairs:</p>
<p>
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:</p>
<p class="code">BEGIN
<p class="code">BEGIN
PRINT 'A' /? THIS BEGINS AND ENDS A COMMENT ?/
PRINT 'A' /? THIS BEGINS AND ENDS A COMMENT ?/
LABEL: * THIS IS MODEL 204 OLD-STYLE COMMENT LINE
LABEL: * THIS IS MODEL 204 OLD-STYLE COMMENT LINE
<b></b>** AND SO IS THIS ONE
<b></b>** AND SO IS THIS ONE
PRINT 'B' /? MORE COMMENTS BEGIN HERE  
PRINT 'B' /? MORE COMMENTS BEGIN HERE
<b></b>* ?/  /? * AND CONTINUE
<b></b>* ?/  /? * AND CONTINUE
           AND CONTINUE (STILL INSIDE COMMENT  
           AND CONTINUE (STILL INSIDE COMMENT
           DELIMITERS)
           DELIMITERS)
           AND THEY FINALLY END HERE  ?/  'C'
           AND THEY FINALLY END HERE  ?/  'C'
END
END
 
A
A
BC
BC
</p>
</p>
<p>For example, the following command prints the values of the LVTBL and LQTBL parameters, to illustrate that you can use the new comments delimiter pair on command statements: </p>
<p>
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: </p>
<p class="code">VIEW /? THIS IS COMMENT1
<p class="code">VIEW /? THIS IS COMMENT1
         AND IT CONTUES
         AND IT CONTINUES
     /? AND IT CONTINUES
     /? AND IT CONTINUES
     ?/ AND IT STILL CONTINUES (ONLY 1 PAIR CLOSED)
     ?/ AND IT STILL CONTINUES (ONLY 1 PAIR CLOSED)
         AND COMMENT1 ENDS HERE ?/ LVTBL, /? CONTINUE LINE WITH
         AND COMMENT1 ENDS HERE ?/ LVTBL, /? CONTINUE LINE WITH
         COMMENT2 AND END COMMENT2 ?/ LQTBL  /? FINALLY WE ARE  
         COMMENT2 AND END COMMENT2 ?/ LQTBL  /? FINALLY WE ARE
         FINISHED ?/
         FINISHED ?/
LVTBL  3100  LENGTH OF VTBL
LVTBL  3100  LENGTH OF VTBL
LQTBL  8490  LENGTH OF QTBL
LQTBL  8490  LENGTH OF QTBL
</p>
</p>
===Compilation termination and request cancellation===
 
====Stopping compilation====
==Compilation termination and request cancellation==
<p>If you are entering a request and want to stop after compilation and before evaluation, you can enter this statement: </p>
 
<p class="code">END NORUN
<div id="Stopping compilation"></div>
<div id="endStmt"></div>
===Stopping compilation: the End statement===
<!--Caution: <div>s above-->
The syntax of the <var>End</var> statment is:
<p class="syntax">End [NoRun] [More [Use]]</p>
<p>
If you are entering a request and want to stop after compilation and before evaluation, you can enter this statement: </p>
<p class="code">end norun
</p>
</p>
<p>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#Procedures|Procedures]].</p>
<p>
====Cancelling a request====
<var>End NoRun</var> 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#Procedures|Procedures]].</p>
<p>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 Rocket <var class="product">Model&nbsp;204</var> Terminal User's Guide for a detailed description of the attention key used for each terminal or access method.   </p>
<p>
<p>These methods of cancellation are most helpful to the user who is receiving unexpected responses or prompts from <var class="product">Model&nbsp;204</var>. When a request is being entered, the cancellation has the same effect as END NORUN. Control is returned to command level. </p>
<var>End More</var> terminates the request but allows continuation of the request with the <var>[[MORE command|More]]</var> command.  Specifying <var>Use</var> in addition to <var>More</var> keeps any USE dataset in effect open for the request continuation.</p>
<p>Additional information:</p>
 
===Cancelling a request===
<p>
The <var>*CANCEL</var> 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|Category:Terminal processing and support]] page to locate a detailed description of the attention key used for each terminal or access method. </p>
<p>
These methods of cancellation are most helpful to the user who is receiving unexpected responses or prompts from <var class="product">Model&nbsp;204</var>. When a request is being entered, the cancellation has the same effect as <var>End NoRun</var>. Control is returned to command level. </p>
<p>
Additional information:</p>
<ul>
<ul>
<li>[[Subroutines#ON units|ON units]]</li>
<li>[[On statement|On units]]</li>
</li>
 
<li>[[Procedures#Using *CANCEL to return to command level|Using *CANCEL to return to command level]]</li>
<li>[[Procedures#Using *CANCEL to return to command level|Using *CANCEL to return to command level]]</li>
</li>
</ul>
</ul>
[[Category:SOUL]]
[[Category:SOUL]]

Latest revision as of 21:51, 2 January 2018

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:

  • Consist of an asterisk followed by a line of hyphens because the final hyphen is interpreted as a continuation character.
  • Contain ??, ?$, or ?& because these strings are interpreted as dummy string prompts. Refer to Procedures for more information about dummy strings.
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: