Basic SOUL statements and commands: Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(98 intermediate revisions by 5 users not shown)
Line 1: Line 1:
===Overview===
<p>
<p>This chapter discusses in more detail the basic statements that can be used within a request. This chapter also presents the system control commands that you commonly use during a terminal session. There are many more User Language statements and [[:Category:Commands|commands]] than are presented here.</p>
This page discusses in more detail the basic statements that can be used within a request. This page also presents the system control commands that you commonly use during a terminal session. There are many more SOUL statements and [[:Category:Commands|commands]] than are presented here. </p>
 
__TOC__
===System control commands===
 
<p>Before learning about User Language statements, it is important to understand the role of <var class="product">Model&nbsp;204</var> commands that are required for basic request processing.</p>
==System control commands==
====Use of commands with requests====
<p>
<p>System control commands are used outside requests to perform system level operations such as opening files and saving requests. Although system control commands are not part of User Language, many commands you might find useful are illustrated in examples throughout this manual. </p>
Before learning about SOUL statements, it is important to understand the role of <var class="product">Model&nbsp;204</var> commands that are required for basic request processing. </p>
<p>Complete descriptions of these and other commands are included in [[:Category:Commands|commands]].   </p>
 
===Use of commands with requests===
====Key commands====
<p>
<p>The following system control commands are essential to allow User Language requests to function:  </p>
System control commands are used outside requests to perform system level operations such as opening files and saving requests. Although system control commands are not part of SOUL, many commands you might find useful are found in examples of SOUL constructs. </p>
<p>
Complete descriptions of these and other commands are included in [[:Category:Commands|commands]]. </p>
===Key commands===
<p>
The following system control commands are essential to allow SOUL requests to function:  </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 15: Line 21:
<th>Action</th>
<th>Action</th>
</tr>
</tr>
<tr>
<tr>
<td>BEGIN </td>
<td><var>[[BEGIN command|BEGIN]]</var></td>
<td>Initiates a User Language request.</td>
<td>Initiates a User Language request.</td>
</tr>
</tr>
<tr>
<tr>
<td><var>OPEN</var> </td>
<td><var>[[OPEN FILE command|OPEN]]</var> </td>
<td>Opens a <var class="product">Model&nbsp;204</var> file or group. See [[Files, Groups, and Reference Context#OPEN or OPENC statement|OPEN or OPENC statement]] for a detailed discussion of the OPEN statement. Refer to [[#IN clauses|IN clauses]] for a discussion of using the IN clause when several files are open.</td>
<td>Opens a <var class="product">Model&nbsp;204</var> file or group. See [[Files, groups, and reference context#OPEN statement and OPENC statement|Open statement and OpenC statement]] for a detailed discussion of the OPEN statement. Refer to [[#IN clauses|IN clauses]] for a discussion of using the IN clause when several files are open.</td>
</tr>
</tr>
<tr>
<tr>
<td><var>CLOSE</var> </td>
<td><var>[[CLOSE command|CLOSE]]</var> </td>
<td>Closes a <var class="product">Model&nbsp;204</var> file or group that has been opened.   </td>
<td>Closes a <var class="product">Model&nbsp;204</var> file or group that has been opened. </td>
</tr>
</tr>
</table>
</table>
<p>The MORE command and END MORE statement are discussed in the section [[#Request continuation|Request continuation]] and in [[Large Request Considerations#Large Request Considerations|Large Request Considerations]].</p>
<p>
<div id="findRecords"></div>
The <var>MORE</var> command and <var>End More</var> statement are discussed in the [[#Request continuation|Request continuation]] and [[Large request considerations]] sections. </p>
===FIND statement===
 
<p>You can retrieve sets of records, records with specified characteristics, and individual records. </p>
==<b id="findRecords"></b>Find statement==
<p>The basic retrieval statement in User Language is the FIND statement. Several forms of the FIND statement are provided for basic and complex retrievals. Basic retrieval statements are discussed in this chapter. See [[Record Retrievals#Record Retrievals|Record Retrievals]] for a discussion of more complex retrieval statements.   </p>
<p>
====FIND ALL RECORDS statement====
You can retrieve sets of records, records with specified characteristics, and individual records. </p>
<p>
The basic retrieval statement in SOUL is the <var>Find</var> statement. Several forms of the <var>Find</var> statement are provided for basic and complex retrievals. Basic retrieval statements are discussed in this topic. See [[Record retrievals]] for a discussion of more complex retrieval statements. </p>
<p>
The complete syntax is presented on the <var>[[Find Records statement|Find Records]]</var> statement page, including its various forms such as <var>Find Without Locks</var> (which is abbreviated <var>FDWOL</var>). </p>
===Find All Records statement===
<b>Syntax</b>
<b>Syntax</b>
<p>The syntax for retrieving records in a <var class="product">Model&nbsp;204</var> file is:</p>
<p>
<p class="syntax"><span class="term">label</span>: FIND ALL RECORDS
The syntax for retrieving records in a <var class="product">Model&nbsp;204</var> file is: </p>
 
<p class="syntax"><span class="term">label</span>: Find All Records
[IN {FILE <span class="term">filename</span> | GROUP <span class="term">groupname</span>}] -
[In {File <span class="term">filename</span> | Group <span class="term">groupname</span>}] -
Find [And Reserve] [All] Records -
[In <span class="term">label</span> | On [List] <span class="term">listname</span>] -
For Which | With] <span class="term">retrieval-conditions</span>
. . .
End Find
</p>
<b>Where</b>
<ul>
<li><var class="term">filename</var> specifies the file that has the records you want to retrieve.</li>


FIND [AND RESERVE] [ALL] RECORDS -
<li><var class="term">groupname</var> specifies the group of files that has the records you want to retrieve.</li>


[IN <span class="term">label</span> | ON [LIST] <span class="term">listname</span>] -
<li><var class="term">label</var> specifies the label of a preceding <var>Find</var> statement. </li>


FOR WHICH | WITH] <span class="term">retrieval-conditions</span>
<li><var class="term">listname</var> specifies a list from a preceding <var>Find</var> statement.</li>


. . . . .
<li>The <i>retrieval-conditions</i> can be:
END FIND
<p class="syntax">[<span class="term">fieldname</span> {Eq | Ne} Value In <span class="term">value_set</span>] </p>
<p>
<var class="term">fieldname</var> identifies the field from which to retrieve values. </p>
<p>
The <var class="term">value_set</var> label represents an existing value set. Values of the value set in the <var>Eq Value In <i>value_set</i></var> clause are treated as boolean OR, for example:
</p>
</p>
<b>Where</b>
<p class="syntax"><span class="term">field</span> = <span class="term">value1</span> OR <span class="term">field</span> = <span class="term">value2</span> OR.... </p>
<ul>
<p>
<li><i>filename</i> specifies the file that has the records you want to retrieve.</li>
The <var>Ne Value In <i>value_set</i></var> clause is likewise treated as boolean AND, for example:
</li>
<li><i>groupname</i> specifies the group of files that has the records you want to retrieve.</li>
</li>
<li><i>label</i> specifies the label of a preceding FIND statement. </li>
</li>
<li><i>listname</i> specifies a list from a preceding FIND statement.</li>
</li>
<li>The <i>retrieval-conditions</i> can be:</li>
<p class="syntax">[<span class="term">fieldname</span> {EQ | NE} VALUE IN <span class="term">value_set</span>]
</p></li>
</ul>
<p><i>fieldname</i> identifies the field from which to retrieve values.</p>
<p>The <i>value_set</i> label represents an existing value set. Values of the value set in the EQ VALUE IN <i>value_set</i> clause are treated as boolean OR, for example:</p>
<p class="syntax"><span class="term">field</span> = <span class="term">value1</span> OR <span class="term">field</span> = <span class="term">value2</span> OR....
</p>
</p>
<p>The NE VALUE IN <i>value_set</i> clause is likewise treated as boolean AND, for example:</p>
<p class="syntax"><span class="term">field</span> <> <span class="term">value1</span> AND <span class="term">field</span> <> <span class="term">value2</span> AND....
<p class="syntax"><span class="term">field</span> <> <span class="term">value1</span> AND <span class="term">field</span> <> <span class="term">value2</span> AND....
</p>
</p>
<p>
For the full variety of possible retrieval conditions, see [[Statement syntax#Retrieval condition syntax|Retrieval condition syntax]]. </p></li>
</ul>
<b>Example</b>
<b>Example</b>
<p>A basic FIND statement is coded as follows: </p>
<p>
A basic <var>Find</var> statement is coded as follows: </p>
<p class="code">FIND.RECS: FIND ALL RECORDS
<p class="code">FIND.RECS: FIND ALL RECORDS
           END FIND
           END FIND
</p>
</p>


====Ending a FIND statement====
===Ending a Find statement===
<p>Except where noted in this manual, you must end a FIND statement with either an END FIND statement or a label. A FIND statement cannot be ended by an END BLOCK statement.       </p>
<p>
Except where explicitly noted, you must end a <var>Find</var> statement with either an <var>End Find</var> statement or a label. A <var>Find</var> statement cannot be ended by an <var>End Block</var> statement. </p>
<b>Syntax</b>
<b>Syntax</b>
<p>The format of the END FIND statement is:</p>
<p>
<p class="syntax">END FIND [<span class="term">label</span>]  
The format of the <var>End Find</var> statement is:  
</p>
<p class="syntax">End Find [<span class="term">label</span>]
</p>
</p>
<p>In addition, the retrieval conditions of a FIND statement must not be labeled, even if they begin new lines.</p>
<p>
 
In addition, the retrieval conditions of a <var>Find</var> statement must not be labeled, even if they begin new lines.</p>
====Large Object data support====
<p>The FIND statement supports Large Object data in the following format:</p>
===Large Object data support===
<p class="syntax">FIND <span class="term">lob-fieldname</span> IS [NOT] PRESENT
<p>
The <var>Find</var> statement supports Large Object data in the following format:</p>
<p class="syntax">Find <span class="term">lob-fieldname</span> Is [Not] Present
</p>
</p>


===Understanding retrieval conditions===
==Understanding retrieval conditions==
====Processing a VALUE IN clause====
<p>You can incorporate a VALUE IN clause in the following User Language statements: </p>
===<b id="valueIn"></b>Processing a VALUE IN clause===
<p>
You can incorporate a <var>Value In</var> clause in the following SOUL statements: </p>
<ul>
<ul>
<li>FIND ALL RECORDS: see <i>retrieval-conditions</i> in [[#FIND ALL RECORDS statement|FIND ALL RECORDS statement]]</li>
<li><var>Find All Records</var>: see <i>retrieval-conditions</i> in the <var>[[#FIND ALL RECORDS statement|Find All Records]]</var> statement</li>
</li>
 
<li>FIND ALL VALUES: see [[Value Loops#FIND ALL VALUES statement|FIND ALL VALUES statement]] </li>
<li><var>Find All Values</var>: see <var>[[Value loops#FIND ALL VALUES statement|Find All Values]]</var> statement</li>
</li>
 
<li>FOR EACH RECORD WHERE: see [[Record Loops#Restricting FOR EACH RECORD processing|Restricting FOR EACH RECORD processing]]</li>
<li><var>For Each Record Where</var>: see [[Record loops#WhereWith|Restricting For Each Record processing]] </li>
</li>
</ul>
</ul>
<p>The VALUE IN clause is valid for fields that include the ORDERED attribute. The interprocessing between fields works between fields of the same ORDERED type: ORDERED CHARACTER or ORDERED NUMERIC. If processing between fields of differing types, you will likely not find records. </p>
<p>
<b>Rewriting applications to take advantage of VALUE IN clause processing</b>
The <var>Value In</var> clause is valid for fields that include the <var>ORDERED</var> attribute. The inter-processing between fields works between fields of the same <var>ORDERED</var> type: <var>ORDERED CHARACTER</var> or <var>ORDERED NUMERIC</var>. If processing between fields of differing types, you will likely not find records. </p>
<p>If your User Language applications now use nested loops to perform join processing, you could rewrite your applications to take advantage of the VALUE IN clause.</p>
<p>You are likely to see performance improvements, which result in a reduction of overall wall clock time due to:</p>
====Rewriting applications to take advantage of Value In clause processing====
<p>
If your SOUL applications now use nested loops to perform join processing, you could rewrite your applications to take advantage of the <var>Value In</var> clause. </p>
<p>
You are likely to see performance improvements, which result in a reduction of overall wall clock time due to:</p>
<ul>
<ul>
<li>A decrease in disk I/O</li>
<li>A decrease in disk I/O</li>
</li>
</li>
<li>Decreases in the number of FINDs and BXFINDs, because the processing has moved. You will see an increase in BXNEXTs </li>
<li>Decreases in the number of <var>Find</var>s and [[Using system statistics#Description of statistics|BXFIND]]s, because the processing has moved. You will see an increase in BXNEXTs </li>
</li>
</li>
</ul>
</ul>
<p>The following code example illustrates the use of a VALUE IN clause:</p>
<p>
The following code example shows a use of the <var>Value In</var> clause: </p>
<p class="code">OPEN CLAIMS90
<p class="code">OPEN CLAIMS90
FILEMGR
FILEMGR
Line 128: Line 161:
</p>
</p>


====FIND ALL RECORDS FOR WHICH/WITH statement====
===FIND ALL RECORDS FOR WHICH/WITH statement===
<p>The basic statement for retrieving data based on specific retrieval conditions is: </p>
<p>
<p class="syntax"><span class="term">label</span>: FIND ALL RECORDS
The basic statement for retrieving data based on specific retrieval conditions is: </p>
 
<p class="syntax"><span class="term">label</span>: Find All Records {For Which | With}
{FOR WHICH | WITH}
 
  {<span class="term">fieldname</span>=<span class="term">value</span> | <span class="term">fieldname</span>=<span class="term">value1</span> Or <span class="term">value2</span>
  {<span class="term">fieldname</span>=<span class="term">value</span> | <span class="term">fieldname</span>=<span class="term">value1</span> OR <span class="term">value2</span>
 
  | <span class="term">fieldname</span> Not=<span class="term">value</span>
  | <span class="term">fieldname</span> NOT=<span class="term">value</span>  
 
  | <span class="term">fieldname</span>=<span class="term">value1</span> And Not=<span class="term">value2</span>
  | <span class="term">fieldname</span>=<span class="term">value1</span> AND NOT=<span class="term">value2</span>
 
  | <span class="term">fieldname</span> Not=<span class="term">value1</span> Nor <span class="term">value2</span>
  | <span class="term">fieldname</span> NOT=<span class="term">value1</span> NOR <span class="term">value2</span>  
 
  | <span class="term">fieldname</span> Is Like <span class="term">pattern</span>}
  | <span class="term">fieldname</span> IS LIKE <span class="term">pattern</span>}
 
  | <span class="term">fieldname</span> {Eq | Ne} Value In <span class="term">value-set</span>
  | <span class="term">fieldname</span> {EQ | NE} VALUE IN <span class="term">value-set</span>
</p>
</p>
<b>Example</b>
<b>Example</b>
<p>This FIND ALL RECORDS FOR WHICH statement directs <var class="product">Model&nbsp;204</var> to look for records of blue Fords:</p>
<p>
This <var>Find All Records For Which</var> statement directs <var class="product">Model&nbsp;204</var> to look for records of blue Fords:</p>
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
               MAKE = FORD
               MAKE = FORD
               COLOR = BLUE
               COLOR = BLUE
           END FIND  
           END FIND
</p>
</p>
<p>This statement contains an AND implied by the fact that COLOR = BLUE appears on a separate line. Only the records containing both fields, MAKE = FORD and COLOR = BLUE, are retrieved.                 </p>
<p>
This statement contains an implied <var>And</var> by the fact that <code>COLOR=BLUE</code> appears on a separate line. Only the records containing both fields, <code>MAKE=FORD</code> and <code>COLOR=BLUE</code>, are retrieved. </p>


===Using expressions for value retrieval===
==Using expressions for value retrieval==
<p>You can use expressions for value retrieval in the following FIND statements:</p>
<p>
You can use expressions for value retrieval in the following <var>Find</var> statements: </p>
<ul>
<ul>
<li>FIND - POINT$ condition</li>
<li><var>Find...Point$</var> condition </li>
<li>FIND - SFL$ and SFGE$ conditions</li>
<li><var>Find...Sfl$</var> and <var>Find...Sfge$</var> conditions </li>
<li>FIND ALL VALUES</li>
<li><var>Find All Values</var> </li>
</ul>
</ul>
<p>For syntax examples, see [[Statement syntax#Retrieval condition syntax|"Retrieval condition syntax"]]. For more information on expression types that you can use to supply retrieval values, see [[Using Variables and Values in Computation#Using expressions for value retrieval|Using expressions for value retrieval]].</p>
<p>
===Using Boolean operators with retrieval statements===
For syntax examples, see [[Statement syntax#Retrieval condition syntax|Retrieval condition syntax]]. For more information on expression types that you can use to supply retrieval values, see [[Using variables and values in computation#Using expressions for value retrieval|Using expressions for value retrieval]]. </p>
<p>You can use the Boolean operators AND, OR, NOT, and NOR to create complex retrieval conditions. In the previous example, the AND could be stated implicitly. Thus this statement:            </p>
 
==Using Boolean operators with retrieval statements==
<p>
You can use the Boolean operators AND, OR, NOT, and NOR to create complex retrieval conditions. In the previous example, the AND could be stated implicitly. Thus this statement:            </p>
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
               MAKE = FORD AND COLOR = BLUE
               MAKE = FORD AND COLOR = BLUE
           END FIND  
           END FIND
</p>
</p>
<p>retrieves the same data as the example in the section above. </p>
<p>
<p>However, the statement:</p>
retrieves the same data as the example in the section above. </p>
<p>
However, the statement:</p>
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
               MAKE = FORD OR COLOR = BLUE
               MAKE = FORD OR COLOR = BLUE
           END FIND  
           END FIND
</p>
</p>
<p>finds records for which either the make is Ford, the color is blue, or both.</p>
<p>
<p>The following statement:</p>
finds records for which either the make is Ford, the color is blue, or both.</p>
<p>
The following statement:</p>
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
               MAKE = NOT FORD NOR COLOR = BLUE
               MAKE = NOT FORD NOR COLOR = BLUE
           END FIND  
           END FIND
</p>
</p>
<p>finds all records other than blue Fords. NOR is the same as AND NOT.          </p>
<p>
====Understanding NOT operator processing====
finds all records other than blue Fords. NOR is the same as AND NOT.          </p>
<b>Creating the complimentary foundset</b>
<p>Although a FIND statement with the NOT operator ultimately returns a foundset that excludes records, <var class="product">Model&nbsp;204</var> FIND processing starts by creating a foundset based on the retrieval without the NOT operator. For the following code example, <var class="product">Model&nbsp;204</var> locates all the records with MAKE=FORD, then returns to you the remainders or complimentary foundset: a foundset of records where MAKE=NOT FORD. </p>
===Understanding NOT operator processing===
====Creating the complimentary foundset====
<p>
Although a FIND statement with the NOT operator ultimately returns a foundset that excludes records, <var class="product">Model&nbsp;204</var> FIND processing starts by creating a foundset based on the retrieval without the NOT operator. For the following code example, <var class="product">Model&nbsp;204</var> locates all the records with MAKE=FORD, then returns to you the remainders or complimentary foundset: a foundset of records where MAKE=NOT FORD. </p>
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
                 MAKE = NOT FORD
                 MAKE = NOT FORD
           END FIND  
           END FIND
</p>
</p>
<p class="note"><b>Note:</b> Records that do not have the MAKE field are not included in either foundset.</p>
<p class="note"><b>Note:</b> Records that do not have the MAKE field are not included in either foundset.</p>
<b>Creating a foundset based on the position of the NOT operator</b>
<p>In the following abstract examples, notice the placement of the NOT operator.</p>
====Creating a foundset based on the position of the NOT operator====
<p>
In the following abstract examples, notice the placement of the NOT operator.</p>
<b>Example A</b>
<b>Example A</b>
<p class="syntax"><span class="term">label1</span>: FIND ALL RECORDS FOR WHICH
<p class="syntax"><span class="term">label1</span>: FIND ALL RECORDS FOR WHICH
         NOT <span class="term">fieldname</span> IS LIKE*
         NOT <span class="term">fieldname</span> IS LIKE*
</p>
</p>
<p>In Example A, <var class="product">Model&nbsp;204</var> locates a found set of the records with <i>fieldname</i>=*: that is, any value. Then <var class="product">Model&nbsp;204</var> applies the NOT operator to <i>fieldname</i> and returns a found set of records that does not include <i>fieldname</i>. This mimics the behavior of IS NOT PRESENT; see [[Record Retrievals#IS PRESENT condition|IS PRESENT condition]].</p>
<p>
In Example A, <var class="product">Model&nbsp;204</var> locates a found set of the records with <i>fieldname</i>=*: that is, any value. Then <var class="product">Model&nbsp;204</var> applies the NOT operator to <i>fieldname</i> and returns a found set of records that does not include <i>fieldname</i>. This mimics the behavior of IS NOT PRESENT; see [[Record retrievals#IS PRESENT condition|IS PRESENT condition]].</p>
<b>Example B</b>
<b>Example B</b>
<p class="syntax"><span class="term">label2</span>: FIND ALL RECORDS FOR WHICH
<p class="syntax"><span class="term">label2</span>: FIND ALL RECORDS FOR WHICH
         <span class="term">fieldname</span> IS NOT LIKE*
         <span class="term">fieldname</span> IS NOT LIKE*
</p>
</p>
<p>In Example B, <var class="product">Model&nbsp;204</var> locates a foundset of the records with <i>fieldname</i>=*: that is, any value. Then <var class="product">Model&nbsp;204</var> applies the NOT operator to LIKE* and returns a foundset of no records, because all values for <i>fieldname</i> have been excluded from the foundset.</p>
<p>
<p>Use the following example data set with three records of defined fields ABC and XYZ to illustrate the differing found sets from the placement of the NOT operator.</p>
In Example B, <var class="product">Model&nbsp;204</var> locates a foundset of the records with <i>fieldname</i>=*: that is, any value. Then <var class="product">Model&nbsp;204</var> applies the NOT operator to LIKE* and returns a foundset of no records, because all values for <i>fieldname</i> have been excluded from the foundset.</p>
<p>
Use the following example data set with three records of defined fields ABC and XYZ to illustrate the differing found sets from the placement of the NOT operator.</p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 229: Line 280:
         NOT XYZ IS LIKE*
         NOT XYZ IS LIKE*
</p>
</p>
<p>The count returned to you is 2: Records 2 and 3.</p>
<p>
The count returned to you is 2: Records 2 and 3.</p>
<b>Repeating Example B</b>
<b>Repeating Example B</b>
<p class="code">LABEL1: FIND ALL RECORDS FOR WHICH
<p class="code">LABEL1: FIND ALL RECORDS FOR WHICH
         XYZ NOT IS LIKE*
         XYZ NOT IS LIKE*
</p>
</p>
<p>The count returned to you is 0.</p>
<p>
 
The count returned to you is 0.</p>
===Loop statements===
<p>Once a set of records or values has been located, the found set can be referred to by using the FOR statement. </p>
==Loop statements==
<p>The FOR statement introduces a loop. The complete set of statements within the loop is performed once for each record or value located. If no record or values are found, the statements in the loop are skipped.</p>
<p>
<p>When a FIND statement refers back to a previous found set and the found set is empty, then the loop for the FIND statement is skipped. Performance for the FIND processing is enhanced because no retrieval is performed. </p>
Once a set of records or values has been located, the found set can be referred to by using the <var>For</var> statement. </p>
====FOR EACH RECORD statement====
<p>
<p>Use the FOR EACH RECORD statement to refer to each record within a set of records located by a FIND statement.</p>
The <var>For</var> statement introduces a loop. The complete set of statements within the loop is performed once for each record or value located. If no record or values are found, the statements in the loop are skipped.</p>
<b>Syntax</b>
<p>
<p>The form of the FOR EACH RECORD statement is:      </p>
When a <var>Find</var> statement refers back to a previous found set and the found set is empty, then the loop for the <var>Find</var> statement is skipped. Performance for the <var>Find</var> processing is enhanced because no retrieval is performed. </p>
<p class="syntax">FOR EACH RECORD IN <span class="term">label</span>  
===For Each Record statement===
<p>
Use the <var>For Each Record</var> statement to refer to each record within a set of records located by a <var>Find</var> statement. </p>
<p>
<b>Syntax</b> </p>
<p>
The simple form of the <var>For Each Record</var> statement follows. For a more complete syntax and description, see the "For Each Record statement" section in [[Record loops#For Each Record statement|Record loops]].
</p>
<p class="syntax">For Each Record In <span class="term">label</span>
</p>
<p>
where <var class="term">label</var> is the label of a preceding <var>Find</var> statement. </p>
<p>
<b>Example</b>  
</p>
</p>
<p>where <i>label</i> is the label of a preceding FIND statement. </p>
<b>Example</b>
<p class="code">FIND.RECS:  FIND ALL RECORDS FOR WHICH
<p class="code">FIND.RECS:  FIND ALL RECORDS FOR WHICH
                 MAKE = FORD
                 MAKE = FORD
Line 255: Line 319:
                 .
                 .
                 .
                 .
             END FOR  
             END FOR
</p>
</p>
<p class="note"><b>Notes:</b>  
<blockquote class="note">
<p><b>Notes:</b> </p>
<ul>
<ul>
<li>The FOR EACH RECORD statement also can be used to combine retrieval and looping when a particular set of records is processed only once in a request.</li>
<li>The <var>For Each Record</var> statement also can be used to combine retrieval and looping when a particular set of records is processed only once in a request. </li>
 
<li><var class="product">Model&nbsp;204</var> also supports a prefetch (look-ahead read) feature, which can provide performance improvements for applications containing FOR EACH RECORD statements. See [[Record Loops#Record Loops|Record Loops]] for more information on the FOR EACH RECORD statement and the prefetch feature.
<li><var class="product">Model&nbsp;204</var> also supports a [[Record loops#The prefetch (look-ahead read) feature|prefetch (look-ahead read) feature]], which can provide performance improvements for applications containing <var>For Each Record</var> statements. </li>
</li>
</ul>
</ul>
</p>
</blockquote>


====Ending a FOR statement====
===Ending a For statement===
<p>The FOR statement must be ended by using an END FOR or an END BLOCK statement. </p>
<p>
<b>Syntax</b>
The <var>For</var> statement must be ended by using an <var>End For</var> or an <var>End Block</var> statement. </p>
<p>The format of the END FOR statement is:   </p>
<p>
<p class="syntax">END FOR [<span class="term">label</span>]  
<b>Syntax</b> </p>
<p>
The format of the <var>End For</var> statement is: </p>
<p class="syntax">End For [<span class="term">label</span>]
</p>
</p>
<p>where <i>label</i> is the label of the line containing the FOR statement.</p>
<p>
where <var class="term">label</var> is the label of the line containing the <var>For</var> statement. </p>
===Nested loops===
<p>
Any loop in SOUL can be nested: embedded in another loop or series of statements. The <var>End For</var> statement returns the nesting level to the same level as the <var>For</var> statement. </p>


====Nested loops====
==IF statement==
<p>Any loop in User Language can be nested: embedded in another loop or series of statements. The END FOR statement returns the nesting level to the same level as the FOR statement.</p>
<p>
===IF statement===
The IF statement tests a condition and then executes one or more statements if the condition is true. </p>
<p>The IF statement tests a condition and then executes one or more statements if the condition is true. </p>
<p>
<p>The IF statement is discussed in detail in [[Flow of Control in User Language#Flow of Control in User Language|Flow of Control in User Language]]. </p>
The IF statement is discussed in detail in [[Flow of control in User Language#Flow of control in User Language]]. </p>
<b>Syntax</b>
<b>Syntax</b>
<p>The format of the IF statement is:</p>
<p>
<p class="code">IF condition THEN statements  
The format of the IF statement is:</p>
<p class="syntax">IF <span class="term">condition</span> THEN <span class="term">statements</span>
</p>
</p>
<p>where condition follows the syntax rules described in [[Statement syntax#Expression syntax|"Expression syntax"]].</p>
<p>
====Ending an IF statement====
where <i>condition</i> follows the syntax rules described in [[Statement syntax#Expression syntax|"Expression syntax"]].</p>
<p>The IF statement must be ended by an END IF statement or an END BLOCK statement. </p>
===Ending an IF statement===
<p>
The IF statement must be ended by an END IF statement or an END BLOCK statement. </p>
<b>Syntax</b>
<b>Syntax</b>
<p>The format of the END IF statement is:</p>
<p>
<p class="code">END IF <var>[</var>label<var>]</var>
The format of the END IF statement is:</p>
<p class="syntax">END IF [<span class="term">label</span>]
</p>
</p>
<b>Example</b>
<b>Example</b>
Line 298: Line 375:
     .
     .
     .
     .
     .  
     .
</p>
</p>
===Counting records===
<p>In addition to retrieving specified records and printing fields from them, you might wish to know the number of records that satisfy a certain condition. Use either of these statements:      </p>
==Counting records==
<p>
In addition to retrieving specified records and printing fields from them, you might wish to know the number of records that satisfy a certain condition. Use either of these statements:      </p>
<ul>
<ul>
<li>COUNT RECORDS IN/ON (or CT)</li>
<li>COUNT RECORDS IN/ON (or CT)</li>
<li>FIND AND PRINT COUNT (or FPC)</li>
<li>FIND AND PRINT COUNT (or FPC)</li>
</ul>
</ul>
====COUNT RECORDS IN/ON statement====
<p>The COUNT RECORDS statement takes two forms:</p>
===COUNT RECORDS IN/ON statement===
<p>
The COUNT RECORDS statement takes two forms:</p>
<ul>
<ul>
<li>COUNT RECORDS IN is used for counting records in a set of records retrieved with the FIND ALL RECORDS statement.</li>
<li>COUNT RECORDS IN is used for counting records in a set of records retrieved with the FIND ALL RECORDS statement.</li>
Line 314: Line 395:
</li>
</li>
</ul>
</ul>
<p>The COUNT RECORDS IN/ON statement is supported in scattered group context. See [[Files, Groups, and Reference Context#Files, Groups, and Reference Context|Files, Groups, and Reference Context]] for more information on the reference context.</p>
<p>
The COUNT RECORDS IN/ON statement is supported in scattered group context. See [[Files, groups, and reference context]] for more information on the reference context.</p>
<b>Syntax</b>
<b>Syntax</b>
<p>The format for the COUNT RECORDS IN statement is:</p>
<p>
<p class="code">label.b: COUNT RECORDS IN label.a  
The format for the COUNT RECORDS IN statement is:</p>
<p class="syntax"><span class="term">label.b</span>: COUNT RECORDS IN <span class="term">label.a</span>
</p>
</p>
<p>where label.a is the label of a previous FIND statement. </p>
<p>
<p>The format for the COUNT RECORDS ON statement is:</p>
where <i>label.a</i> is the label of a previous FIND statement. </p>
<p class="code">label.b: COUNT RECORDS ON list  
<p>
The format for the COUNT RECORDS ON statement is:</p>
<p class="syntax"><span class="term">label.b</span>: COUNT RECORDS ON <span class="term">list</span>
</p>
</p>
<p>where list is the name of a list on which you have previously placed found records.</p>
<p>
<p>For both forms of the COUNT RECORDS statement, you can print the count using the statement:</p>
where <i>list</i> is the name of a list on which you have previously placed found records.</p>
<p class="code">PRINT COUNT IN label.b  
<p>
For both forms of the COUNT RECORDS statement, you can print the count using the statement:</p>
<p class="syntax">PRINT COUNT IN <span class="term">label.b</span>
</p>
</p>
<b>Example</b>
<b>Example</b>
<p>This COUNT RECORDS IN request:</p>
<p>
This COUNT RECORDS IN request:</p>
<p class="code">BEGIN
<p class="code">BEGIN
DRIVER: FIND ALL RECORDS FOR WHICH
DRIVER: FIND ALL RECORDS FOR WHICH
Line 336: Line 424:
CT:    COUNT RECORDS IN DRIVER
CT:    COUNT RECORDS IN DRIVER
         PRINT COUNT IN CT
         PRINT COUNT IN CT
END  
END
</p>
</p>
<p>causes <var class="product">Model&nbsp;204</var> to note that two records were found by the FIND statement. <var class="product">Model&nbsp;204</var> then prints the number 2.   </p>
<p>
====FIND AND PRINT COUNT statement====
causes <var class="product">Model&nbsp;204</var> to note that two records were found by the FIND statement. <var class="product">Model&nbsp;204</var> then prints the number 2.</p>
<p>The FIND AND PRINT COUNT statement is used to combine record retrieval with the COUNT and associated PRINT statements. </p>
===FIND AND PRINT COUNT statement===
<p>
The FIND AND PRINT COUNT statement is used to combine record retrieval with the COUNT and associated PRINT statements. </p>
<b>Example 1</b>
<b>Example 1</b>
<p>This statement:    </p>
<p>
This statement:    </p>
<p class="code">DRIVER: FIND AND PRINT COUNT
<p class="code">DRIVER: FIND AND PRINT COUNT
             RECTYPE = DRIVER
             RECTYPE = DRIVER
             POLICY NO = 100340
             POLICY NO = 100340
         END FIND  
         END FIND
</p>
</p>
<p>is similar to:</p>
<p>
is similar to:</p>
<p class="code">DRIVER: FIND ALL RECORDS FOR WHICH
<p class="code">DRIVER: FIND ALL RECORDS FOR WHICH
             RECTYPE = DRIVER
             RECTYPE = DRIVER
Line 354: Line 447:
         END FIND
         END FIND
CT:    COUNT RECORDS IN DRIVER
CT:    COUNT RECORDS IN DRIVER
         PRINT COUNT IN CT  
         PRINT COUNT IN CT
</p>
</p>
<p>The label for the FIND AND PRINT COUNT statement can be referred to in the same way in which a label for a FIND ALL RECORDS FOR WHICH statement can be used. </p>
<p>
The label for the FIND AND PRINT COUNT statement can be referred to in the same way in which a label for a FIND ALL RECORDS FOR WHICH statement can be used. </p>
<b>Example 2</b>
<b>Example 2</b>
<p>The count found by a FIND AND PRINT COUNT statement cannot be positioned to a specified column. The position defaults to column 1 or the next print location, if preceded by an ellipsis (...).</p>
<p>
<p>For example, this request:</p>
The count found by a FIND AND PRINT COUNT statement cannot be positioned to a specified column. The position defaults to column 1 or the next print location, if preceded by an ellipsis (...).</p>
<p>
For example, this request:</p>
<p class="code">BEGIN
<p class="code">BEGIN
DRIVER: FIND AND PRINT COUNT
DRIVER: FIND AND PRINT COUNT
Line 368: Line 464:
             PRINT FULLNAME
             PRINT FULLNAME
         END FOR
         END FOR
END  
END
</p>
</p>
<p>results in this output:</p>
<p>
results in this output:</p>
<p class="code">2
<p class="code">2
ABBOTT, FRANKLIN G
ABBOTT, FRANKLIN G
ABBOTT, GAIL H     
ABBOTT, GAIL H
</p>
==Output statements for fields and field groups==
<p>
Print statements are often used in loops to display information from each record located by a FIND statement. </p>
<p>
Two of the statements described in this section, PRINT ALL INFORMATION and PRINT <i>fieldname</i>, are basic output statements. PRINT ALL INFORMATION and PRINT <i>fieldname</i> can be used only in a record loop.</p>
<p>
The PAI INTO statement, an extension of the PAI statement, allows you to store the field names and values associated with a record in an array. See [[Record loops]] for more information.</p>
<p>
More complex statements are used for variable format output. These are discussed in [[Report generation]].</p>
 
The following User Language statements provide display output for Model 204.
 
<p class="note"><b>Note:</b> Field group processing is generally available as of Model 204 version 7.5.</p>
<p class="code">AUDIT ALL FIELDGROUP INFORMATION (AAFGI)
AUDIT ALL INFORMATION (AAI)
PRINT ALL FIELDGROUP INFORMATION (PAFGI)
PRINT ALL INFORMATION (PAI)
</p>
 
AUDIT statement processing is just like PRINT statement processing, except the output goes to the audit trail. The PRINT ALL FIELDGROUP INFORMATION and the AUDIT ALL FIELDGROUP INFORMATION statements do the equivalent of a PAI statement that is limited to the current context field group.
 
If you just want to display the contents of the third occurrence of field group FOO, you could issue the following statement:
<p class="code">IN FILE WHATEVER FRN %RECNO
   FOR FIELDGROUP FOO(3)
      PRINT ’*** Third occurrence of field group FOO’
      PAFGI
  END FOR
END FOR
</p>
 
===Statements using the CTOFIELDS argument===
Usually you would not want to display a counter (CTO) field when you use the
following statements:
<p class="code">PRINT ALL INFORMATION (PAI)
AUDIT ALL INFORMATION (AAI)
PRINT ALL FIELDGROUP INFORMATION (PAFGI)
AUDIT ALL FIELDGROUP INFORMATION (AAFGI)
</p>
</p>
===Output statements===
 
<p>Print statements often are used in loops to display information from each record located by a FIND statement. </p>
However, when you need that information you can use the argument to indicate that you do want a counter (CTO) field to be printed by these statements.
<p>The two statements described in this section, PRINT ALL INFORMATION and PRINT fieldname, are basic output statements. PRINT ALL INFORMATION and PRINT fieldname can be used only in a record loop.</p>
<p class="code">PAI CTOFIELDS
<p>The PAI INTO statement, an extension of the PAI statement, allows you to store the field names and values associated with a record in an array. See [[Record Loops#PAI INTO statement|PAI INTO statement]] for more information.</p>
</p>
<p>More complex statements are used for variable format output. These are discussed in [[Report Generation#Report Generation|Report Generation]].</p>
 
====PRINT ALL INFORMATION (or PAI) statement====
===<b id="aafgiStmt"></b>Audit All Fieldgroup Information (AAFGI) statement===
<b>Purpose</b>
<p>
<p>The PRINT ALL INFORMATION (or PAI) statement causes output of whole records. </p>
<b>Purpose</b> </p>
<p>
<var>Audit All Fieldgroup Information</var> (<var>AAFGI</var>) writes the output of the current field group to the audit trail.</p>
<p>The same information can be displayed on the terminal using the
<var>[[PAFGI statement|PAFGI]]</var> statement.</p>
<b>Syntax</b>
<p>The form of the AAFGI statement is:</p>
{{Template:AAFGI statement syntax}}
<b>Where</b>
<p>If <var>CtOFields</var> is specified, the <var>[[Field design#cto|COUNT-OCCURRENCES-OF]]</var>
(<var>CTO</var>) field(s) are audited. By default <var>CTO</var> fields are not audited.</p>
 
===Audit All Information statement===
<b>Purpose</b>  
<p>
The <var>Audit All Information</var> (or <var>AAI</var>) statement writes the output of entire records to the [[Report generation#Audit All Information statement|audit trail]]. </p>
<p>
<b>Syntax</b> </p>
<p>
The form of the <var>AAI</var> statement is: </p>
{{Template:Audit All Information statement syntax}}
<p>
<b>Where</b> </p>
<p>
<var>CtoFields</var> specifies to print the counter (CTO) field(s). By default CTO fields are not printed. </p>
 
===<b id="pafgiStmt"></b>Print All Fieldgroup Information (PAFGI) statement===
<p>
<b>Purpose</b> </p>
<p>
The <var>Print All Fieldgroup Information</var> (<var>PAFGI</var>) statement writes the output of the current fieldgroup to the terminal.</p>
<p>The <var>[[AAFGI statement|AAFGI]]</var> statement displays the same information but is routed to the audit trail.</p>
<b>Syntax</b>
<b>Syntax</b>
<p>The form of the PAI statement is:</p>
<p>
<p class="code">PRINT ALL INFORMATION option
The form of the <var>PAFGI</var> statement is: </p>
{{Template:PAFGI statement syntax}}
Where:
<ul>
<li><var class="term">lob-option</var> can be one of the following and specifies how Large Object fields are handled.
<ul>
<li><var>Lob_Flod</var>, the default, which means output in a format that FLOD can read and reload Large Object fields. The output includes the descriptor in binary format, plus the full field value. </li>
 
<li><var>Lob_Data</var> specifies whether to display the field value. The <var>PAFGI</var> statement displays the Large Object descriptor in printable format. </li>
 
<li><var>Lob_Short_Data</var> specifies to display the first 255 bytes of the field value. The <var>PAFGI</var> statement displays the Large Object descriptor in printable
format. </li>
 
<li><var>Lob_No_Data</var> specifies not to display the value. However, the <var>PAFGI</var> statement displays the Large Object descriptor in printable format. </li>
 
<li><var>Lob_None</var>, which says not to display any Large Object fields. </li>
</ul></li>
 
<li><var>CtoFields</var> specifies to print the counter (<var>CTO</var>) field(s). By default <var>CTO</var>
fields are not printed. </li>
</ul>
<p>
<b>Example</b> </p>
This example shows printed terminal output from <var>PAFGI</var> and audit trail output from <var>AAFGI</var>:
<p class="code">fr where policy_number = 100095
  feo fieldgroup driver
      print '---' and driver_name and '---'
      audit '---' and driver_name and '---'
      pafgi
      aafgi
  end for
end for
</p>
Printed output:
<p class="output">--- ALTON, BARBARA W ---
\DRIVER = 1
DRIVER_ID = 100223
DRIVER_NAME = ALTON, BARBARA W
DRIVER_MARITAL_STATUS = MARRIED
DRIVER_GENDER = F
DRIVER_DATE_OF_BIRTH = 19280311
/DRIVER = 1
......
</p>
Audit trail output:
<p class="output">10189103542 30  2    9 US --- ALTON, BARBARA W ---
10189103542 31  2    9 US \DRIVER = 1
10189103542 32  2    9 US DRIVER_ID = 100223
10189103542 33  2    9 US DRIVER_NAME = ALTON, BARBARA W
10189103542 34  2    9 US DRIVER_MARITAL_STATUS = MARRIED
10189103542 35  2    9 US DRIVER_GENDER = F
10189103542 36  2    9 US DRIVER_DATE_OF_BIRTH = 19280311
10189103542 37  2    9 US /DRIVER = 1
...and so on...
</p>
</p>
<p>where option can be one of the following and specifies how Large Object fields are handled.</p>
 
===<b id="PAI"></b>PRINT ALL INFORMATION (or PAI) statement===
<p>
<b>Purpose</b> </p>
<p>
The <var>Print All Information</var> (or <var>PAI</var>) statement causes output of whole records. </p>
<b>Syntax</b>
<p>
The format of the <var>PAI</var> statement is: </p>
{{Template:PAI statement syntax}}
<p>
Where: </p>
<ul>
<li>At most one Lob option can be specified for large object display:
<ul>
<ul>
<li>LOB_FLOD, the default, which means output in a format that FLOD can read and reload Large Object fields. The output includes the descriptor in binary format, plus the full field value.</li>
<li><var>Lob_Flod</var>, the default, specifies output in a format that Flod can read and reload Large Object fields. The output includes the descriptor in binary format, plus the full field value.</li>
</li>
 
<li>LOB_DATA specifies whether to display the field value. The PAI statement displays the Large Object descriptor in printable format.</li>
<li><var>Lob_Data</var> specifies whether to display the field value. The <var>PAI</var> statement displays the Large Object descriptor in printable format.</li>
</li>
 
<li>LOB_SHORT_DATA specifies to display the first 255 bytes of the field value. The PAI statement displays the Large Object descriptor in printable format.</li>
<li><var>Lob_Short_Data</var> specifies to display the first 255 bytes of the field value. The <var>PAI</var> statement displays the Large Object descriptor in printable format.</li>
</li>
 
<li>LOB_NO_DATA specifies not to display the value. However, the PAI statement displays the Large Object descriptor in printable format.</li>
<li><var>Lob_No_Data</var> specifies not to display the value. However, the <var>PAI</var>
</li>
<li><var>Lob_None</var> specifies not to display any Large Object fields. </li>
<li>LOB_NONE, which says not to display any Large Object fields.</li>
</ul></li>
</li>
 
<li><var>CtoFields</var> specifies that the counter (<var>CTO</var>) field(s) should be printed. By default, <var>CTO</var> fields are not printed.
<p class="note"><b>Note:</b>
The <var>CtoFields</var> keyword and a <var>Lob_</var>xxx keyword can be in either order, but neither of them can follow the <var>Into</var> clause. </p></li>
 
<li>The <var>Into</var> clause is not used for display purposes. It lets you move a record's field names and values into a form of storage that can be easily manipulated. For details, see [[Record loops#paiInto|Print All Information (or PAI) Into statement]].</li>
</ul>
</ul>
<b>Example</b>
 
<p>This request:</p>
====Examples====
<ul>
<li><div id="FIND results">
Displaying FIND results</div>
<p>
This request:</p>
<p class="code">BEGIN
<p class="code">BEGIN
FIND.RECS: FIND ALL RECORDS FOR WHICH
FIND.RECS: FIND ALL RECORDS FOR WHICH
Line 410: Line 656:
               PRINT ALL INFORMATION
               PRINT ALL INFORMATION
           END FOR
           END FOR
END  
END
</p>
</p>
<p>results in output with the format:</p>
<p>
<p class="code">FULLNAME = ABBOTT, GAIL H
results in output with the following format:</p>
<p class="output">FULLNAME = ABBOTT, GAIL H
POLICY NO = 100340
POLICY NO = 100340
DRIVER ID = 100817
DRIVER ID = 100817
Line 423: Line 670:
INCIDENT = T3
INCIDENT = T3
INCIDENT DATE = 19900921
INCIDENT DATE = 19900921
DATE OF BIRTH = 19390305  
DATE OF BIRTH = 19390305
</p></li>
 
<li>Displaying counter fields
<p>
This request:</p>
<p class="code">BEGIN
FR WHERE POLICY_NUMBER = 100000
  PAI CTOFIELDS
END FOR
END
</p>
<p>
results in output with the following format (note the inclusion of the <var>CTO</var> fields <code>NUMBER_OF_DRIVERS</code> and <code>NUMBER_OF_VEHICLES</code>): </p>
<p class="output">ADDRESS = 3621 GLEN CT
POLICY_NUMBER = 100000
NUMBER_OF_DRIVERS = 4
NUMBER_OF_VEHICLES = 3
...and so on...
\DRIVER = 1
DRIVER_ID = 100001
DRIVER_NAME = ALLEN, MARGARET E
...and so on...
/DRIVER = 1
\DRIVER = 2
DRIVER_ID = 100002
DRIVER_NAME = ALLEN, RAY F
...and so on...
</p></li>
 
<li>Displaying fields of different storage types, including non-preallocated, preallocated, and the <var>EXACTLY-ONE</var> type
<p>
This definition and request:</p>
<p class="code">DEFINE FIELD PORD1 ( ORD CHAR OCC 1 LEN 4 )
DEFINE FIELD EORD1 ( ORD CHAR EXACTLY-ONE )
DEFINE FIELD NORD1 ( ORD CHAR            )
BEGIN
IN F100A STORE RECORD
  PORD1 = FRED
  EORD1 = JANE
  NORD1 = STEV
END STORE
END
 
BEGIN
  FOR EACH RECORD
    PAI
    PRINT
  END FOR
END</p>
<p>
results in output with the following format. Note the output of the <var>EXACTLY-ONE</var> field first in the list, followed by the preallocated field, and finally the non-preallocated field: </p>
<p class="output">EORD1 = JANE
PORD1 = FRED
NORD1 = STEV
</p>
</p>
====INVISIBLE fields not printed====
<p>
<p>In the example on the previous page, the fieldname = value pair,
Because <var>EXACTLY-ONE</var> fields are always present but are not always physically stored in the record, it is most efficient to display them first in the <var>PAI</var> statement. If there are no <var>EXACTLY-ONE</var> fields defined to the file, then the order of printing will be any preallocated fields (in the order in which they were defined to the file), followed by any non preallocated fields (in the order in which they are stored within the record). </p></li>
RECTYPE = DRIVER, is not printed in the output because the RECTYPE field has the INVISIBLE attribute. </p>
</ul>
<p>For more information about the INVISIBLE attribute, refer to the Rocket <var class="product">Model&nbsp;204</var> File Manager's Guide. </p>
 
====PRINT fieldname statement====
===INVISIBLE fields are not printed===
<p>
A field defined with the <var>INVISIBLE</var> attribute cannot be printed, noted, or sorted.</p>
<p>
The previous [[#FIND results|"Displaying FIND results" example]] shows a fieldname = value pair (<code>RECTYPE=DRIVER</code>) that is not printed in the output because the field (<code>RECTYPE</code>) has the <var>INVISIBLE</var> attribute. </p>
<p>
For more information about the <var>INVISIBLE</var> attribute, refer to [[Field design#Field descriptions and attributes|Field descriptions and attributes]]. </p>
 
===PRINT <i>fieldname</i> statement===
<b>Syntax</b>
<b>Syntax</b>
<p>To display the value of a certain field in a record, use this form of the PRINT statement:   </p>
<p>
<p class="code">PRINT fieldname <var>[</var>AND fieldname2<var>]</var>
To display the value of a certain field in a record, use this form of the <var>Print</var> statement:  
</p>
<p class="syntax">Print <span class="term">fieldname</span> [And <span class="term">fieldname2</span>]
</p>
</p>
<b>Example</b>
<b>Example</b>
<p>Here is a sample PRINT fieldname statement:</p>
<p>
Here is a sample <var>Print <i>fieldname</i></var> statement:
</p>
<p class="code">BEGIN
<p class="code">BEGIN
DRIVER: FIND ALL RECORDS FOR WHICH
DRIVER: FIND ALL RECORDS FOR WHICH
Line 444: Line 757:
             PRINT FULLNAME
             PRINT FULLNAME
         END FOR
         END FOR
END  
END </p>
<p>
In response to the above request, <var class="product">Model&nbsp;204</var> prints:</p>
<p class="output">ABBOTT, FRANKLIN G
ABBOTT, GAIL H
</p>
</p>
<p>In response to the above request, <var class="product">Model&nbsp;204</var> prints:</p>
<p>
<p class="code">ABBOTT, FRANKLIN G
Each value of the <code>FULLNAME</code> field is displayed on a new line. A record that has no <code>FULLNAME</code> field produces a blank line of output. </p>
ABBOTT, GAIL H
===Printing several fields===
<p>
The values of more than one field can be printed on the same output line by using the keywords <var>And</var> and <var>With</var>. <var>And</var> causes a space to be printed between values, as in the following example:
</p>
</p>
<p>Each value of the FULLNAME field is displayed on a new line. A record that has no FULLNAME field produces a blank line of output.    </p>
====Printing several fields====
<p>The values of more than one field can be printed on the same output line by using the keywords AND and WITH. AND causes a space to be printed between values, as in the following example:</p>
<p class="code">BEGIN
<p class="code">BEGIN
DRIVER: FIND ALL RECORDS FOR WHICH
DRIVER: FIND ALL RECORDS FOR WHICH
Line 461: Line 778:
             PRINT SEX AND DATE OF BIRTH
             PRINT SEX AND DATE OF BIRTH
         END FOR
         END FOR
END  
END </p>
</p>
<p>
<p>Running the request above results in this output:</p>
Running the request above results in this output:</p>
<p class="code">M 19480204
<p class="output">M 19480204
F 19390305  
F 19390305
</p>
</p>
<p>If a retrieved record has no SEX field, the value of DATE OF BIRTH is printed on a line beginning with a space, as specified by the keyword AND, for example:</p>
<p>
<p class="code">19480204
If a retrieved record has no <code>SEX</code> field, the value of <code>DATE OF BIRTH</code> is printed on a line beginning with a space, as specified by the keyword <var>And</var>, for example:</p>
<p class="output">19480204
</p>
</p>
<p>If a record has neither field, it produces a blank line of output.</p>
<p>
<p>The keyword WITH works like AND except that WITH does not cause a space to be printed between values.              </p>
If a record has neither field, it produces a blank line of output.</p>
====Controlling spacing between output lines====
<p>
<p>The SKIP LINE(S) and NEW PAGE statements enable you to control spacing between lines.</p>
The keyword <var>With</var> works like <var>And</var> except that <var>With</var> does not cause a space to be printed between values.              </p>
<b>SKIP LINE(S)</b>
<p>The SKIP LINE(S) statement directs <var class="product">Model&nbsp;204</var> to skip a specified number of lines before printing the next line of output. If the number of lines remaining on a page is fewer than the number of lines specified, <var class="product">Model&nbsp;204</var> skips the remainder of the lines on the page, starts a new page, and then continues to skip lines until n is reached.    </p>
===Controlling spacing between output lines===
<p>The syntax of the SKIP LINE(S) statement is as follows:</p>
<p>
<p class="code">SKIP {n | %variable} LINE[S]
The <var>Skip Line</var> and <var>New Page</var> statements enable you to control spacing between lines. </p>
====SKIP LINE(S)====
<p>
The SKIP LINE(S) statement directs <var class="product">Model&nbsp;204</var> to skip a specified number of lines before printing the next line of output. If the number of lines remaining on a page is fewer than the number of lines specified, <var class="product">Model&nbsp;204</var> skips the remainder of the lines on the page, starts a new page, and then continues to skip lines until <i>n</i> is reached.    </p>
<p>
The syntax of the SKIP LINE(S) statement is as follows:</p>
<p class="syntax">SKIP {<span class="term">n</span> | %<span class="term">variable</span>} LINE[S]
</p>
</p>
<b>Where</b>
Where:
<ul>
<ul>
<li>n is a positive integer less than or equal to 100. </li>
<li><i>n</i> is a positive integer less than or equal to 100. </li>
</li>
 
<li>%variable is a positive integer from 0 through 100 supplied by a %variable or a :% variable. Field names or %% variables are invalid. </li>
<li>%<i>variable</i> is a positive integer from 0 through 100 supplied by a %variable or a :% variable. Field names or %% variables are invalid. </li>
</li>
</ul>
</ul>
<p>SKIP %variable LINE(S) bypasses the processing and skips no lines if the value of the %variable is zero. However, if n is zero, SKIP n LINES is invalid. </p>
<p>
<p>The SKIP %variable LINE(S) option does not apply to the full-screen SKIP LINE(S) statement, as described on [[Full-Screen Feature#SKIP statement for menus|SKIP statement for menus]].</p>
SKIP %<i>variable</i> LINE(S) bypasses the processing and skips no lines if the value of the %<i>variable</i> is zero. However, if <i>n</i> is zero, SKIP <i>n</i> LINES is invalid. </p>
<b>NEW PAGE</b>
<p>
<p>The NEW PAGE statement directs <var class="product">Model&nbsp;204</var> to start a new page before printing further output.  </p>
The SKIP %<i>variable</i> LINE(S) option does not apply to the full-screen SKIP LINE(S) statement, as described on [[Full-screen feature#SKIP statement for menus|SKIP statement for menus]].</p>
<p>For example, in response to:</p>
 
====NEW PAGE====
<p>
The NEW PAGE statement directs <var class="product">Model&nbsp;204</var> to start a new page before printing further output.  </p>
<p>
For example, in response to:</p>
<p class="code">FOR EACH RECORD IN DRIVER
<p class="code">FOR EACH RECORD IN DRIVER
   NEW PAGE
   NEW PAGE
   PRINT ALL INFORMATION
   PRINT ALL INFORMATION
END FOR  
END FOR
</p>
</p>
<p><var class="product">Model&nbsp;204</var> starts a new page before printing each record.</p>
<p>
====Loading Large Object data====
<var class="product">Model&nbsp;204</var> starts a new page before printing each record.</p>
<p>A <var class="product">Model&nbsp;204</var> file that contains Large Object data can be reorganized using the standard PAI and FLOD procedure described in the Rocket <var class="product">Model&nbsp;204</var> File Manager's Guide, which employs the User Language PAI (PRINT ALL INFORMATION) statement to unload the data from a file, and a standard FLOD program to reload the data. This is identical to previous releases of <var class="product">Model&nbsp;204</var>, and no change to your existing unload or load code is required.</p>
 
===IN clauses===
===Loading Large Object data===
<p>Many User Language statements can be preceded by an IN clause. An IN indicates explicitly the file or group to which a statement applies when several files or groups are open.</p>
A <var class="product">Model&nbsp;204</var> file that contains Large Object data can be reorganized using the standard [[File loading techniques#Loading Large Object Data | PAI and FLOD procedure]], which employs the User Language PAI (PRINT ALL INFORMATION) statement to unload the data from a file, and a standard FLOD program to reload the data. This is identical to previous releases of <var class="product">Model&nbsp;204</var>, and no change to your existing unload or load code is required.
<p>When you do not use the IN clause, <var class="product">Model&nbsp;204</var> acts on the default file as established by the most recently executed OPEN or DEFAULT command.</p>
 
<p>In addition to specifying an individual file or group name, the IN clause has more detailed information about the reference context of the statement it precedes. For example, when you are working with individual remote files, you can specify the location of the file; and when you are working in group context, you can restrict the context of certain statements to one member file in the group by using the IN GROUP MEMBER form of the IN clause.</p>
==IN clauses==
<p>Refer to [[Files, Groups, and Reference Context#Files, Groups, and Reference Context|Files, Groups, and Reference Context]] for more information on the reference context and ways to use the IN clause.</p>
<p>
Many User Language statements can be preceded by an IN clause. An IN indicates explicitly the file or group to which a statement applies when several files or groups are open.</p>
<p>
When you do not use the IN clause, <var class="product">Model&nbsp;204</var> acts on the default file as established by the most recently executed OPEN or DEFAULT command.</p>
<p>
In addition to specifying an individual file or group name, the IN clause has more detailed information about the reference context of the statement it precedes. For example, when you are working with individual remote files, you can specify the location of the file; and when you are working in group context, you can restrict the context of certain statements to one member file in the group by using the IN GROUP MEMBER form of the IN clause.</p>
<p>
Refer to [[Files, groups, and reference context]] for more information on the reference context and ways to use the IN clause.</p>
<b>Syntax</b>
<b>Syntax</b>
<p>The simplest form of the IN clause is:</p>
<p>
<p class="code">IN {filename | groupname} [AT location]  
The simplest form of the IN clause is:</p>
<p class="syntax">IN {<span class="term">filename</span> | <span class="term">groupname</span>} [AT <span class="term">location</span>]
</p>
</p>
<b>Example</b>
<b>Example</b>
<p>This request prints the policy number, body, and make of a policy in the VEHICLES file, and the full name, marital status, and sex of records for that policy number in the CLIENTS file:</p>
<p>
This request prints the policy number, body, and make of a policy in the VEHICLES file, and the full name, marital status, and sex of records for that policy number in the CLIENTS file:</p>
<p class="code">OPEN CLIENTS
<p class="code">OPEN CLIENTS
OPEN VEHICLES
OPEN VEHICLES
Line 527: Line 865:
                   PRINT FULLNAME AND MARITAL STATUS AND SEX
                   PRINT FULLNAME AND MARITAL STATUS AND SEX
               END FOR
               END FOR
END  
END
</p>
</p>
<p>The output from this request would be:</p>
<p>
The output from this request would be:</p>
<p class="code">100340 4DR DATSUN
<p class="code">100340 4DR DATSUN
ABBOTT, FRANKLIN G SINGLE M
ABBOTT, FRANKLIN G SINGLE M
ABBOTT, GAIL H SINGLE F  
ABBOTT, GAIL H SINGLE F
</p>
</p>
===Request continuation===
<p>Lengthy requests can be handled by using the END MORE statement and the MORE command. See [[Large Request Considerations#Large Request Considerations|Large Request Considerations]] for more information on request continuation, including a discussion of the MORE command and the END MORE statement and its USE option.             </p>
==Request continuation==
<p>
Lengthy requests can be handled by using the END MORE statement and the MORE command. See [[Large request considerations]] for more information on request continuation, including a discussion of the MORE command and the END MORE statement and its USE option. </p>
<b>Example</b>
<b>Example</b>
<p>The sample request below tells you how many records exist in a given file for female drivers registered in Florida:</p>
<p>
The sample request below tells you how many records exist in a given file for female drivers registered in Florida:</p>
<p class="code">BEGIN
<p class="code">BEGIN
GET.DRIVER: FIND AND PRINT COUNT
GET.DRIVER: FIND AND PRINT COUNT
Line 544: Line 886:
                 SEX = F
                 SEX = F
             END FIND
             END FIND
END MORE  
END MORE
</p>
</p>
<p>After printing its output, this request returns you to command level. Using the MORE command, you can continue the request, adding further statements as well as referring to the results of statements in the original request. If, for example, you wanted to perform further processing of the records found in the original request without repeating the FIND operation, you could enter the following lines, referencing the label GET.DRIVER:</p>
<p>
After printing its output, this request returns you to command level. Using the MORE command, you can continue the request, adding further statements as well as referring to the results of statements in the original request. If, for example, you wanted to perform further processing of the records found in the original request without repeating the FIND operation, you could enter the following lines, referencing the label <code>GET.DRIVER</code>:</p>
<p class="code">MORE
<p class="code">MORE
        FOR EACH RECORD IN GET.DRIVER
    FOR EACH RECORD IN GET.DRIVER
            PRINT FULLNAME AND DATE OF BIRTH
        PRINT FULLNAME AND DATE OF BIRTH
        END FOR
    END FOR
END    
END
</p>
</p>
<p>&nbsp;</p>
 
<b>F</b>
==See also==
 
[[SOUL statements]]
 
[[Category:SOUL]]
[[Category:SOUL]]

Latest revision as of 00:20, 19 June 2018

This page discusses in more detail the basic statements that can be used within a request. This page also presents the system control commands that you commonly use during a terminal session. There are many more SOUL statements and commands than are presented here.

System control commands

Before learning about SOUL statements, it is important to understand the role of Model 204 commands that are required for basic request processing.

Use of commands with requests

System control commands are used outside requests to perform system level operations such as opening files and saving requests. Although system control commands are not part of SOUL, many commands you might find useful are found in examples of SOUL constructs.

Complete descriptions of these and other commands are included in commands.

Key commands

The following system control commands are essential to allow SOUL requests to function:

Command Action
BEGIN Initiates a User Language request.
OPEN Opens a Model 204 file or group. See Open statement and OpenC statement for a detailed discussion of the OPEN statement. Refer to IN clauses for a discussion of using the IN clause when several files are open.
CLOSE Closes a Model 204 file or group that has been opened.

The MORE command and End More statement are discussed in the Request continuation and Large request considerations sections.

Find statement

You can retrieve sets of records, records with specified characteristics, and individual records.

The basic retrieval statement in SOUL is the Find statement. Several forms of the Find statement are provided for basic and complex retrievals. Basic retrieval statements are discussed in this topic. See Record retrievals for a discussion of more complex retrieval statements.

The complete syntax is presented on the Find Records statement page, including its various forms such as Find Without Locks (which is abbreviated FDWOL).

Find All Records statement

Syntax

The syntax for retrieving records in a Model 204 file is:

label: Find All Records [In {File filename | Group groupname}] - Find [And Reserve] [All] Records - [In label | On [List] listname] - For Which | With] retrieval-conditions . . . End Find

Where

  • filename specifies the file that has the records you want to retrieve.
  • groupname specifies the group of files that has the records you want to retrieve.
  • label specifies the label of a preceding Find statement.
  • listname specifies a list from a preceding Find statement.
  • The retrieval-conditions can be:

    [fieldname {Eq | Ne} Value In value_set]

    fieldname identifies the field from which to retrieve values.

    The value_set label represents an existing value set. Values of the value set in the Eq Value In value_set clause are treated as boolean OR, for example:

    field = value1 OR field = value2 OR....

    The Ne Value In value_set clause is likewise treated as boolean AND, for example:

    field <> value1 AND field <> value2 AND....

    For the full variety of possible retrieval conditions, see Retrieval condition syntax.

Example

A basic Find statement is coded as follows:

FIND.RECS: FIND ALL RECORDS END FIND

Ending a Find statement

Except where explicitly noted, you must end a Find statement with either an End Find statement or a label. A Find statement cannot be ended by an End Block statement.

Syntax

The format of the End Find statement is:

End Find [label]

In addition, the retrieval conditions of a Find statement must not be labeled, even if they begin new lines.

Large Object data support

The Find statement supports Large Object data in the following format:

Find lob-fieldname Is [Not] Present

Understanding retrieval conditions

Processing a VALUE IN clause

You can incorporate a Value In clause in the following SOUL statements:

The Value In clause is valid for fields that include the ORDERED attribute. The inter-processing between fields works between fields of the same ORDERED type: ORDERED CHARACTER or ORDERED NUMERIC. If processing between fields of differing types, you will likely not find records.

Rewriting applications to take advantage of Value In clause processing

If your SOUL applications now use nested loops to perform join processing, you could rewrite your applications to take advantage of the Value In clause.

You are likely to see performance improvements, which result in a reduction of overall wall clock time due to:

  • A decrease in disk I/O
  • Decreases in the number of Finds and BXFINDs, because the processing has moved. You will see an increase in BXNEXTs

The following code example shows a use of the Value In clause:

OPEN CLAIMS90 FILEMGR REDEFINE FIELD POLICY NO (ORD CHAR) OPEN CLIENTS FILEMGR REDEFINE FIELD POLICY NO (ORD CHAR) BEGIN /? FIND ALL CLIENTS WHO MADE CLAIMS ?/ CLAIM.POLICYS: IN CLAIMS90 FDV POLICY NO CLIENT.FD: IN CLIENTS FD POLICY NO EQ VALUE IN CLAIM.POLICYS END FIND FR CLIENT.FD PRINT POLICY NO AND FULLNAME END FOR END

FIND ALL RECORDS FOR WHICH/WITH statement

The basic statement for retrieving data based on specific retrieval conditions is:

label: Find All Records {For Which | With} {fieldname=value | fieldname=value1 Or value2 | fieldname Not=value | fieldname=value1 And Not=value2 | fieldname Not=value1 Nor value2 | fieldname Is Like pattern} | fieldname {Eq | Ne} Value In value-set

Example

This Find All Records For Which statement directs Model 204 to look for records of blue Fords:

FIND.RECS: FIND ALL RECORDS FOR WHICH MAKE = FORD COLOR = BLUE END FIND

This statement contains an implied And by the fact that COLOR=BLUE appears on a separate line. Only the records containing both fields, MAKE=FORD and COLOR=BLUE, are retrieved.

Using expressions for value retrieval

You can use expressions for value retrieval in the following Find statements:

  • Find...Point$ condition
  • Find...Sfl$ and Find...Sfge$ conditions
  • Find All Values

For syntax examples, see Retrieval condition syntax. For more information on expression types that you can use to supply retrieval values, see Using expressions for value retrieval.

Using Boolean operators with retrieval statements

You can use the Boolean operators AND, OR, NOT, and NOR to create complex retrieval conditions. In the previous example, the AND could be stated implicitly. Thus this statement:

FIND.RECS: FIND ALL RECORDS FOR WHICH MAKE = FORD AND COLOR = BLUE END FIND

retrieves the same data as the example in the section above.

However, the statement:

FIND.RECS: FIND ALL RECORDS FOR WHICH MAKE = FORD OR COLOR = BLUE END FIND

finds records for which either the make is Ford, the color is blue, or both.

The following statement:

FIND.RECS: FIND ALL RECORDS FOR WHICH MAKE = NOT FORD NOR COLOR = BLUE END FIND

finds all records other than blue Fords. NOR is the same as AND NOT.

Understanding NOT operator processing

Creating the complimentary foundset

Although a FIND statement with the NOT operator ultimately returns a foundset that excludes records, Model 204 FIND processing starts by creating a foundset based on the retrieval without the NOT operator. For the following code example, Model 204 locates all the records with MAKE=FORD, then returns to you the remainders or complimentary foundset: a foundset of records where MAKE=NOT FORD.

FIND.RECS: FIND ALL RECORDS FOR WHICH MAKE = NOT FORD END FIND

Note: Records that do not have the MAKE field are not included in either foundset.

Creating a foundset based on the position of the NOT operator

In the following abstract examples, notice the placement of the NOT operator.

Example A

label1: FIND ALL RECORDS FOR WHICH NOT fieldname IS LIKE*

In Example A, Model 204 locates a found set of the records with fieldname=*: that is, any value. Then Model 204 applies the NOT operator to fieldname and returns a found set of records that does not include fieldname. This mimics the behavior of IS NOT PRESENT; see IS PRESENT condition.

Example B

label2: FIND ALL RECORDS FOR WHICH fieldname IS NOT LIKE*

In Example B, Model 204 locates a foundset of the records with fieldname=*: that is, any value. Then Model 204 applies the NOT operator to LIKE* and returns a foundset of no records, because all values for fieldname have been excluded from the foundset.

Use the following example data set with three records of defined fields ABC and XYZ to illustrate the differing found sets from the placement of the NOT operator.

Record number Field ABC Field XYZ
1 14 11
2 25  
3 7  

Repeating Example A

LABEL1: FIND ALL RECORDS FOR WHICH NOT XYZ IS LIKE*

The count returned to you is 2: Records 2 and 3.

Repeating Example B

LABEL1: FIND ALL RECORDS FOR WHICH XYZ NOT IS LIKE*

The count returned to you is 0.

Loop statements

Once a set of records or values has been located, the found set can be referred to by using the For statement.

The For statement introduces a loop. The complete set of statements within the loop is performed once for each record or value located. If no record or values are found, the statements in the loop are skipped.

When a Find statement refers back to a previous found set and the found set is empty, then the loop for the Find statement is skipped. Performance for the Find processing is enhanced because no retrieval is performed.

For Each Record statement

Use the For Each Record statement to refer to each record within a set of records located by a Find statement.

Syntax

The simple form of the For Each Record statement follows. For a more complete syntax and description, see the "For Each Record statement" section in Record loops.

For Each Record In label

where label is the label of a preceding Find statement.

Example

FIND.RECS: FIND ALL RECORDS FOR WHICH MAKE = FORD END FIND PRINT.MODEL: FOR EACH RECORD IN FIND.RECS . . . END FOR

Notes:

  • The For Each Record statement also can be used to combine retrieval and looping when a particular set of records is processed only once in a request.
  • Model 204 also supports a prefetch (look-ahead read) feature, which can provide performance improvements for applications containing For Each Record statements.

Ending a For statement

The For statement must be ended by using an End For or an End Block statement.

Syntax

The format of the End For statement is:

End For [label]

where label is the label of the line containing the For statement.

Nested loops

Any loop in SOUL can be nested: embedded in another loop or series of statements. The End For statement returns the nesting level to the same level as the For statement.

IF statement

The IF statement tests a condition and then executes one or more statements if the condition is true.

The IF statement is discussed in detail in Flow of control in User Language#Flow of control in User Language.

Syntax

The format of the IF statement is:

IF condition THEN statements

where condition follows the syntax rules described in "Expression syntax".

Ending an IF statement

The IF statement must be ended by an END IF statement or an END BLOCK statement.

Syntax

The format of the END IF statement is:

END IF [label]

Example

FOR EACH RECORD IN FIND.RECS IF TOTAL PREMIUM = 300 THEN PRINT POLICY NO END IF END FOR . . .

Counting records

In addition to retrieving specified records and printing fields from them, you might wish to know the number of records that satisfy a certain condition. Use either of these statements:

  • COUNT RECORDS IN/ON (or CT)
  • FIND AND PRINT COUNT (or FPC)

COUNT RECORDS IN/ON statement

The COUNT RECORDS statement takes two forms:

  • COUNT RECORDS IN is used for counting records in a set of records retrieved with the FIND ALL RECORDS statement.
  • COUNT RECORDS ON is used for counting records on a list. See Lists for more about lists.

The COUNT RECORDS IN/ON statement is supported in scattered group context. See Files, groups, and reference context for more information on the reference context.

Syntax

The format for the COUNT RECORDS IN statement is:

label.b: COUNT RECORDS IN label.a

where label.a is the label of a previous FIND statement.

The format for the COUNT RECORDS ON statement is:

label.b: COUNT RECORDS ON list

where list is the name of a list on which you have previously placed found records.

For both forms of the COUNT RECORDS statement, you can print the count using the statement:

PRINT COUNT IN label.b

Example

This COUNT RECORDS IN request:

BEGIN DRIVER: FIND ALL RECORDS FOR WHICH RECTYPE = DRIVER POLICY NO = 100340 END FIND CT: COUNT RECORDS IN DRIVER PRINT COUNT IN CT END

causes Model 204 to note that two records were found by the FIND statement. Model 204 then prints the number 2.

FIND AND PRINT COUNT statement

The FIND AND PRINT COUNT statement is used to combine record retrieval with the COUNT and associated PRINT statements.

Example 1

This statement:

DRIVER: FIND AND PRINT COUNT RECTYPE = DRIVER POLICY NO = 100340 END FIND

is similar to:

DRIVER: FIND ALL RECORDS FOR WHICH RECTYPE = DRIVER POLICY NO = 100340 END FIND CT: COUNT RECORDS IN DRIVER PRINT COUNT IN CT

The label for the FIND AND PRINT COUNT statement can be referred to in the same way in which a label for a FIND ALL RECORDS FOR WHICH statement can be used.

Example 2

The count found by a FIND AND PRINT COUNT statement cannot be positioned to a specified column. The position defaults to column 1 or the next print location, if preceded by an ellipsis (...).

For example, this request:

BEGIN DRIVER: FIND AND PRINT COUNT RECTYPE = DRIVER POLICY NO = 100340 END FIND FOR EACH RECORD IN DRIVER PRINT FULLNAME END FOR END

results in this output:

2 ABBOTT, FRANKLIN G ABBOTT, GAIL H

Output statements for fields and field groups

Print statements are often used in loops to display information from each record located by a FIND statement.

Two of the statements described in this section, PRINT ALL INFORMATION and PRINT fieldname, are basic output statements. PRINT ALL INFORMATION and PRINT fieldname can be used only in a record loop.

The PAI INTO statement, an extension of the PAI statement, allows you to store the field names and values associated with a record in an array. See Record loops for more information.

More complex statements are used for variable format output. These are discussed in Report generation.

The following User Language statements provide display output for Model 204.

Note: Field group processing is generally available as of Model 204 version 7.5.

AUDIT ALL FIELDGROUP INFORMATION (AAFGI) AUDIT ALL INFORMATION (AAI) PRINT ALL FIELDGROUP INFORMATION (PAFGI) PRINT ALL INFORMATION (PAI)

AUDIT statement processing is just like PRINT statement processing, except the output goes to the audit trail. The PRINT ALL FIELDGROUP INFORMATION and the AUDIT ALL FIELDGROUP INFORMATION statements do the equivalent of a PAI statement that is limited to the current context field group.

If you just want to display the contents of the third occurrence of field group FOO, you could issue the following statement:

IN FILE WHATEVER FRN %RECNO FOR FIELDGROUP FOO(3) PRINT ’*** Third occurrence of field group FOO’ PAFGI END FOR END FOR

Statements using the CTOFIELDS argument

Usually you would not want to display a counter (CTO) field when you use the following statements:

PRINT ALL INFORMATION (PAI) AUDIT ALL INFORMATION (AAI) PRINT ALL FIELDGROUP INFORMATION (PAFGI) AUDIT ALL FIELDGROUP INFORMATION (AAFGI)

However, when you need that information you can use the argument to indicate that you do want a counter (CTO) field to be printed by these statements.

PAI CTOFIELDS

Audit All Fieldgroup Information (AAFGI) statement

Purpose

Audit All Fieldgroup Information (AAFGI) writes the output of the current field group to the audit trail.

The same information can be displayed on the terminal using the PAFGI statement.

Syntax

The form of the AAFGI statement is:

{AAFGI | Audit All Fieldgroup Information} [lob-option] [CtoFields]

Where

If CtOFields is specified, the COUNT-OCCURRENCES-OF (CTO) field(s) are audited. By default CTO fields are not audited.

Audit All Information statement

Purpose

The Audit All Information (or AAI) statement writes the output of entire records to the audit trail.

Syntax

The form of the AAI statement is:

{Audit All Information | AAI} [CtoFields]

Where

CtoFields specifies to print the counter (CTO) field(s). By default CTO fields are not printed.

Print All Fieldgroup Information (PAFGI) statement

Purpose

The Print All Fieldgroup Information (PAFGI) statement writes the output of the current fieldgroup to the terminal.

The AAFGI statement displays the same information but is routed to the audit trail.

Syntax

The form of the PAFGI statement is:

{PAFGI | Print All Fieldgroup Information} [lob-option] [CtoFields]

Where:

  • lob-option can be one of the following and specifies how Large Object fields are handled.
    • Lob_Flod, the default, which means output in a format that FLOD can read and reload Large Object fields. The output includes the descriptor in binary format, plus the full field value.
    • Lob_Data specifies whether to display the field value. The PAFGI statement displays the Large Object descriptor in printable format.
    • Lob_Short_Data specifies to display the first 255 bytes of the field value. The PAFGI statement displays the Large Object descriptor in printable format.
    • Lob_No_Data specifies not to display the value. However, the PAFGI statement displays the Large Object descriptor in printable format.
    • Lob_None, which says not to display any Large Object fields.
  • CtoFields specifies to print the counter (CTO) field(s). By default CTO fields are not printed.

Example

This example shows printed terminal output from PAFGI and audit trail output from AAFGI:

fr where policy_number = 100095 feo fieldgroup driver print '---' and driver_name and '---' audit '---' and driver_name and '---' pafgi aafgi end for end for

Printed output:

--- ALTON, BARBARA W --- \DRIVER = 1 DRIVER_ID = 100223 DRIVER_NAME = ALTON, BARBARA W DRIVER_MARITAL_STATUS = MARRIED DRIVER_GENDER = F DRIVER_DATE_OF_BIRTH = 19280311 /DRIVER = 1 ......

Audit trail output:

10189103542 30 2 9 US --- ALTON, BARBARA W --- 10189103542 31 2 9 US \DRIVER = 1 10189103542 32 2 9 US DRIVER_ID = 100223 10189103542 33 2 9 US DRIVER_NAME = ALTON, BARBARA W 10189103542 34 2 9 US DRIVER_MARITAL_STATUS = MARRIED 10189103542 35 2 9 US DRIVER_GENDER = F 10189103542 36 2 9 US DRIVER_DATE_OF_BIRTH = 19280311 10189103542 37 2 9 US /DRIVER = 1 ...and so on...

PRINT ALL INFORMATION (or PAI) statement

Purpose

The Print All Information (or PAI) statement causes output of whole records.

Syntax

The format of the PAI statement is:

{PAI | Print All Information}
[Lob_Flod | Lob_Data | Lob_Short_Data | Lob_No_Data | Lob_None]
[CtoFields]
[Into array1, array2 [, array3] [From start] [Count ct] ]

Where:

  • At most one Lob option can be specified for large object display:
    • Lob_Flod, the default, specifies output in a format that Flod can read and reload Large Object fields. The output includes the descriptor in binary format, plus the full field value.
    • Lob_Data specifies whether to display the field value. The PAI statement displays the Large Object descriptor in printable format.
    • Lob_Short_Data specifies to display the first 255 bytes of the field value. The PAI statement displays the Large Object descriptor in printable format.
    • Lob_No_Data specifies not to display the value. However, the PAI
    • Lob_None specifies not to display any Large Object fields.
  • CtoFields specifies that the counter (CTO) field(s) should be printed. By default, CTO fields are not printed.

    Note: The CtoFields keyword and a Lob_xxx keyword can be in either order, but neither of them can follow the Into clause.

  • The Into clause is not used for display purposes. It lets you move a record's field names and values into a form of storage that can be easily manipulated. For details, see Print All Information (or PAI) Into statement.

Examples

  • Displaying FIND results

    This request:

    BEGIN FIND.RECS: FIND ALL RECORDS FOR WHICH RECTYPE = DRIVER FULLNAME = ABBOTT, GAIL H END FIND FOR EACH RECORD IN FIND.RECS PRINT ALL INFORMATION END FOR END

    results in output with the following format:

    FULLNAME = ABBOTT, GAIL H POLICY NO = 100340 DRIVER ID = 100817 MARITAL STATUS = SINGLE SEX = F STATE = CALIFORNIA INCIDENT = T1 INCIDENT DATE = 19890820 INCIDENT = T3 INCIDENT DATE = 19900921 DATE OF BIRTH = 19390305

  • Displaying counter fields

    This request:

    BEGIN FR WHERE POLICY_NUMBER = 100000 PAI CTOFIELDS END FOR END

    results in output with the following format (note the inclusion of the CTO fields NUMBER_OF_DRIVERS and NUMBER_OF_VEHICLES):

    ADDRESS = 3621 GLEN CT POLICY_NUMBER = 100000 NUMBER_OF_DRIVERS = 4 NUMBER_OF_VEHICLES = 3 ...and so on... \DRIVER = 1 DRIVER_ID = 100001 DRIVER_NAME = ALLEN, MARGARET E ...and so on... /DRIVER = 1 \DRIVER = 2 DRIVER_ID = 100002 DRIVER_NAME = ALLEN, RAY F ...and so on...

  • Displaying fields of different storage types, including non-preallocated, preallocated, and the EXACTLY-ONE type

    This definition and request:

    DEFINE FIELD PORD1 ( ORD CHAR OCC 1 LEN 4 ) DEFINE FIELD EORD1 ( ORD CHAR EXACTLY-ONE ) DEFINE FIELD NORD1 ( ORD CHAR ) BEGIN IN F100A STORE RECORD PORD1 = FRED EORD1 = JANE NORD1 = STEV END STORE END BEGIN FOR EACH RECORD PAI PRINT END FOR END

    results in output with the following format. Note the output of the EXACTLY-ONE field first in the list, followed by the preallocated field, and finally the non-preallocated field:

    EORD1 = JANE PORD1 = FRED NORD1 = STEV

    Because EXACTLY-ONE fields are always present but are not always physically stored in the record, it is most efficient to display them first in the PAI statement. If there are no EXACTLY-ONE fields defined to the file, then the order of printing will be any preallocated fields (in the order in which they were defined to the file), followed by any non preallocated fields (in the order in which they are stored within the record).

INVISIBLE fields are not printed

A field defined with the INVISIBLE attribute cannot be printed, noted, or sorted.

The previous "Displaying FIND results" example shows a fieldname = value pair (RECTYPE=DRIVER) that is not printed in the output because the field (RECTYPE) has the INVISIBLE attribute.

For more information about the INVISIBLE attribute, refer to Field descriptions and attributes.

PRINT fieldname statement

Syntax

To display the value of a certain field in a record, use this form of the Print statement:

Print fieldname [And fieldname2]

Example

Here is a sample Print fieldname statement:

BEGIN DRIVER: FIND ALL RECORDS FOR WHICH RECTYPE = DRIVER POLICY NO = 100340 END FIND FOR EACH RECORD IN DRIVER PRINT FULLNAME END FOR END

In response to the above request, Model 204 prints:

ABBOTT, FRANKLIN G ABBOTT, GAIL H

Each value of the FULLNAME field is displayed on a new line. A record that has no FULLNAME field produces a blank line of output.

Printing several fields

The values of more than one field can be printed on the same output line by using the keywords And and With. And causes a space to be printed between values, as in the following example:

BEGIN DRIVER: FIND ALL RECORDS FOR WHICH RECTYPE = DRIVER POLICY NO = 100340 END FIND FOR EACH RECORD IN DRIVER PRINT SEX AND DATE OF BIRTH END FOR END

Running the request above results in this output:

M 19480204 F 19390305

If a retrieved record has no SEX field, the value of DATE OF BIRTH is printed on a line beginning with a space, as specified by the keyword And, for example:

19480204

If a record has neither field, it produces a blank line of output.

The keyword With works like And except that With does not cause a space to be printed between values.

Controlling spacing between output lines

The Skip Line and New Page statements enable you to control spacing between lines.

SKIP LINE(S)

The SKIP LINE(S) statement directs Model 204 to skip a specified number of lines before printing the next line of output. If the number of lines remaining on a page is fewer than the number of lines specified, Model 204 skips the remainder of the lines on the page, starts a new page, and then continues to skip lines until n is reached.

The syntax of the SKIP LINE(S) statement is as follows:

SKIP {n | %variable} LINE[S]

Where:

  • n is a positive integer less than or equal to 100.
  • %variable is a positive integer from 0 through 100 supplied by a %variable or a :% variable. Field names or %% variables are invalid.

SKIP %variable LINE(S) bypasses the processing and skips no lines if the value of the %variable is zero. However, if n is zero, SKIP n LINES is invalid.

The SKIP %variable LINE(S) option does not apply to the full-screen SKIP LINE(S) statement, as described on SKIP statement for menus.

NEW PAGE

The NEW PAGE statement directs Model 204 to start a new page before printing further output.

For example, in response to:

FOR EACH RECORD IN DRIVER NEW PAGE PRINT ALL INFORMATION END FOR

Model 204 starts a new page before printing each record.

Loading Large Object data

A Model 204 file that contains Large Object data can be reorganized using the standard PAI and FLOD procedure, which employs the User Language PAI (PRINT ALL INFORMATION) statement to unload the data from a file, and a standard FLOD program to reload the data. This is identical to previous releases of Model 204, and no change to your existing unload or load code is required.

IN clauses

Many User Language statements can be preceded by an IN clause. An IN indicates explicitly the file or group to which a statement applies when several files or groups are open.

When you do not use the IN clause, Model 204 acts on the default file as established by the most recently executed OPEN or DEFAULT command.

In addition to specifying an individual file or group name, the IN clause has more detailed information about the reference context of the statement it precedes. For example, when you are working with individual remote files, you can specify the location of the file; and when you are working in group context, you can restrict the context of certain statements to one member file in the group by using the IN GROUP MEMBER form of the IN clause.

Refer to Files, groups, and reference context for more information on the reference context and ways to use the IN clause.

Syntax

The simplest form of the IN clause is:

IN {filename | groupname} [AT location]

Example

This request prints the policy number, body, and make of a policy in the VEHICLES file, and the full name, marital status, and sex of records for that policy number in the CLIENTS file:

OPEN CLIENTS OPEN VEHICLES BEGIN VEHICLE.RECS: IN VEHICLES AT BOSTON FIND ALL RECORDS FOR WHICH OWNER POLICY = 100340 VIN = DAT7100707 END FIND FOR EACH RECORD IN VEHICLE.RECS PRINT OWNER POLICY AND BODY AND MAKE END FOR DRIVER: IN CLIENTS FIND ALL RECORDS FOR WHICH RECTYPE = DRIVER POLICY NO = 100340 END FIND FOR EACH RECORD IN DRIVER PRINT FULLNAME AND MARITAL STATUS AND SEX END FOR END

The output from this request would be:

100340 4DR DATSUN ABBOTT, FRANKLIN G SINGLE M ABBOTT, GAIL H SINGLE F

Request continuation

Lengthy requests can be handled by using the END MORE statement and the MORE command. See Large request considerations for more information on request continuation, including a discussion of the MORE command and the END MORE statement and its USE option.

Example

The sample request below tells you how many records exist in a given file for female drivers registered in Florida:

BEGIN GET.DRIVER: FIND AND PRINT COUNT RECTYPE = DRIVER STATE = FLORIDA SEX = F END FIND END MORE

After printing its output, this request returns you to command level. Using the MORE command, you can continue the request, adding further statements as well as referring to the results of statements in the original request. If, for example, you wanted to perform further processing of the records found in the original request without repeating the FIND operation, you could enter the following lines, referencing the label GET.DRIVER:

MORE FOR EACH RECORD IN GET.DRIVER PRINT FULLNAME AND DATE OF BIRTH END FOR END

See also

SOUL statements