Lists: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (→‎DECLARE LIST syntax: link repair)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
===Overview===
<!-- div class="toclimit-3" -->
<p>The set of records retrieved by the FIND statement cannot be modified, except from within a record loop. However, a found record set can be copied onto the your own named list and that list then can be modified by using a special set of User Language statements. The resulting list can be accessed by any statement that normally refers to a FIND statement.</p>
 
<p><var class="product">Model&nbsp;204</var> can repeat a series of nested statements against a predefined list of records. Record loops can be executed once for each record in a list and new lists can be generated. This chapter identifies the statements used to create, maintain, and loop on a list of records.             </p>
==Overview==
===Creating and clearing a list===
<p>
<p>You can create a list in one of two ways:</p>
The set of records retrieved by the FIND statement cannot be modified, except from within a record loop. However, a found record set can be copied onto the your own named list and that list then can be modified by using a special set of User Language statements. The resulting list can be accessed by any statement that normally refers to a FIND statement.</p>
<p>
<var class="product">Model&nbsp;204</var> can repeat a series of nested statements against a predefined list of records. Record loops can be executed once for each record in a list and new lists can be generated.
This page identifies the statements used to create, maintain, and loop on a list of records.   </p>
==Creating and clearing a list==
<p>
You can create a list in one of two ways:</p>
<ul>
<ul>
<li>By referring to a list with a PLACE RECORDS IN statement</li>
<li>By referring to a list with a PLACE RECORDS IN statement</li>
<li>By explicitly declaring a list using a form of the DECLARE statement</li>
<li>By explicitly declaring a list using a form of the DECLARE statement</li>
</ul>
</ul>
<p>You can create a list using this statement:  </p>
<p>
<b>Syntax</b>
You can create a list using this statement:  </p>
<p class="code">PLACE RECORDS IN label ON [LIST] listname  
====Syntax====
<p class="syntax">PLACE RECORDS IN <span class="term">label</span> ON [LIST] <span class="term">listname</span>
</p>
</p>
<p>The PLACE RECORDS IN statement is supported in scattered group context.</p>
<p>
<b>Example</b>
The <var>PLACE RECORDS IN</var> statement is supported in scattered group context.</p>
<p>This request demonstrates the use of the PLACE RECORDS IN statement:</p>
 
====Example====
<p>
This request demonstrates the use of the PLACE RECORDS IN statement:</p>
<p class="code">BEGIN
<p class="code">BEGIN
CARPOOLERS:  FIND ALL RECORDS FOR WHICH
CARPOOLERS:  FIND ALL RECORDS FOR WHICH
Line 20: Line 32:
             END FIND
             END FIND
             FOR EACH RECORD IN CARPOOLERS
             FOR EACH RECORD IN CARPOOLERS
DRIVER:        NOTE PRINCIPLE DRIVER
DRIVER:        NOTE PRINCIPAL DRIVER
NO.CP:          FIND ALL RECORDS FOR WHICH
NO.CP:          FIND ALL RECORDS FOR WHICH
                   PRINCIPLE DRIVER = VALUE IN DRIVER
                   PRINCIPAL DRIVER = VALUE IN DRIVER
                   USAGE = NOT CARPOOL
                   USAGE = NOT CARPOOL
                 END FIND
                 END FIND
Line 29: Line 41:
LIST.CT:    COUNT RECORDS ON LIST OTHERCAR
LIST.CT:    COUNT RECORDS ON LIST OTHERCAR
PRINT.CT:    PRINT COUNT IN LIST.CT
PRINT.CT:    PRINT COUNT IN LIST.CT
END  
END
</p>
</p>
<p>The CREATE.LIST statement creates a list of records. During each repetition of the FOR EACH RECORD loop, records are added to the list. The total number is then counted by the LIST.CT statement and printed by the PRINT.CT statement.  </p>
<p>
====List names====
The CREATE.LIST statement creates a list of records. During each repetition of the FOR EACH RECORD loop, records are added to the list. The total number is then counted by the LIST.CT statement and printed by the PRINT.CT statement.  </p>
<p>A list must have a name, like OTHERCAR in the example above.  The list name is made up of a string of alphanumeric characters as many as 255 characters in length.</p>
 
<p>More than one list can be used in a request, but each must have a distinct name. </p>
===List names===
<b>DECLARE LIST syntax</b>
<p>
<p>You can also create a list by using this form of the DECLARE statement:</p>
A list must have a name, like OTHERCAR in the example above.  The list name is made up of a string of alphanumeric characters as many as 255 characters in length.</p>
<p class="code">DECLARE LIST listname  
<p>
   [IN [FILE |[PERM | TEMP] GROUP] filename]
More than one list can be used in a request, but each must have a distinct name. </p>
   [AT location] [COMMON | GLOBAL]
====DECLARE LIST syntax====
<p>
You can also create a list by using this form of the DECLARE statement:</p>
<p class="syntax">DECLARE LIST <span class="term">listname</span>
   [IN [FILE |[PERM | TEMP] GROUP] <span class="term">filename</span>]
   [AT <span class="term">location</span>] [COMMON | GLOBAL]
</p>
</p>
<p>If a list is not declared, it is created when it is first referenced, for example, with a PLACE RECORDS statement. [[Flow of Control in User Language#Flow of Control in User Language|Flow of Control in User Language]] discusses the DECLARE statement in detail.  </p>
<p>
<p>The DECLARE LIST statement is supported in remote file and scattered group contexts.</p>
If a list is not declared, it is created when it is first referenced, for example, with a PLACE RECORDS statement. [[Using variables and values in computation#Declaring %variables and %variable arrays|Declaring %variables and %variable arrays]] discusses the DECLARE statement in detail.  </p>
====Duration of a list====
<p>
<p>Once it is created, you can refer to any list for the duration of the request. Lists which have not been declared GLOBAL are automatically cleared at the beginning of a request, so that no records listed in previous requests remain. Global lists are stored for reference by future requests. See [[Global Features#Global Features|Global Features]] for more information on global found sets and lists.</p>
The DECLARE LIST statement is supported in remote file and scattered group contexts.</p>
<p>A list created during a request that ends with END MORE is stored for future use by requests that begin with MORE, even if the list was not originally declared GLOBAL (see [[Large Request Considerations#Large Request Considerations|Large Request Considerations]]). </p>
 
====Unique inclusion of records on a list====
===Duration of a list===
<p>Each record appears only once on a list, even if it is placed there repeatedly. Therefore lists can be used to eliminate redundancies in multiple sets of records. Consider this example:</p>
<p>
Once it is created, you can refer to any list for the duration of the request. Lists which have not been declared GLOBAL are automatically cleared at the beginning of a request, so that no records listed in previous requests remain. Global lists are stored for reference by future requests. See [[Global features]] for more information on global found sets and lists.</p>
<p>
A list created during a request that ends with END MORE is stored for future use by requests that begin with MORE, even if the list was not originally declared GLOBAL (see [[Large request considerations]]). </p>
===Unique inclusion of records on a list===
<p>
Each record appears only once on a list, even if it is placed there repeatedly. Therefore lists can be used to eliminate redundancies in multiple sets of records. Consider this example:</p>
<p class="code">BEGIN
<p class="code">BEGIN
CAL.POL.HLDR: IN CLIENTS FIND ALL RECORDS FOR WHICH
CAL.POL.HLDR: IN CLIENTS FIND ALL RECORDS FOR WHICH
Line 60: Line 85:
                 .
                 .
                 .
                 .
                 .  
                 .
</p>
</p>
<p>Records of California policy holders, or records for which the agent is Goodrich, are found by this request. Although some records can satisfy both of these conditions, they appear on the list only once. However, the user can still access each set of records separately by referring back to their corresponding FIND labels.</p>
<p>
====Clearing a list====
Records of California policy holders, or records for which the agent is Goodrich, are found by this request. Although some records can satisfy both of these conditions, they appear on the list only once. However, the user can still access each set of records separately by referring back to their corresponding FIND labels.</p>
<p>This statement removes all records from the named list:</p>
<p class="code">CLEAR LIST listname  
===Clearing a list===
<p>
This statement removes all records from the named list:</p>
<p class="syntax">CLEAR LIST <span class="term">listname</span>
</p>
</p>
<p>If the CLEAR LIST statement is the first reference to the named list in the request, then CLEAR LIST creates and initializes the named list. </p>
<p>
<p>The CLEAR LIST statement normally clears an existing list; no IN clause is required. When a CLEAR LIST statement appears in a request before the first reference to the list, an IN clause might be necessary to create the list in the same context as the later references. References to an existing set of records in the CLEAR LIST or FIND statement override the IN clause. </p>
If the CLEAR LIST statement is the first reference to the named list in the request, then CLEAR LIST creates and initializes the named list. </p>
<p>The CLEAR LIST statement is supported in remote file and scattered group contexts.</p>
<p>
<p>You can use the IN GROUP MEMBER clause to restrict the CLEAR LIST to one member of a group. For more information, see [[Files, Groups, and Reference Context#IN GROUP MEMBER clause|IN GROUP MEMBER clause]].</p>
The CLEAR LIST statement normally clears an existing list; no IN clause is required. When a CLEAR LIST statement appears in a request before the first reference to the list, an IN clause might be necessary to create the list in the same context as the later references. References to an existing set of records in the CLEAR LIST or FIND statement override the IN clause. </p>
===Maintaining lists===
<p>
<p>User Language supplies three statements that provide the means to copy, augment, and edit lists.       </p>
The CLEAR LIST statement is supported in remote file and scattered group contexts.</p>
<p>For a discussion of adding and deleting records from a list from within a record loop, refer to [[#PLACE RECORD and REMOVE RECORD statements|PLACE RECORD and REMOVE RECORD statements]].</p>
<p>
====Records from sorted sets====
You can use the IN GROUP MEMBER clause to restrict the CLEAR LIST to one member of a group. For more information, see [[Files, groups, and reference context#IN GROUP MEMBER clause|IN GROUP MEMBER clause]].</p>
<p>Lists that contain records from sorted sets are not maintained in sorted order. However, you can explicitly sort any list.</p>
====Adding one list to another====
==Maintaining lists==
<p>To augment the second list with the records on the first, Use the following statement:</p>
<p>
<p class="code">PLACE RECORDS ON <var>[</var>LIST<var>]</var> listname1 ON <var>[</var>LIST<var>]</var> listname2
User Language supplies three statements that provide the means to copy, augment, and edit lists.   </p>
<p>
For a discussion of adding and deleting records from a list from within a record loop, refer to [[#PLACE RECORD and REMOVE RECORD statements|PLACE RECORD and REMOVE RECORD statements]].</p>
 
===Records from sorted sets===
<p>
Lists that contain records from sorted sets are not maintained in sorted order. However, you can explicitly sort any list.</p>  
===Adding one list to another===
<p>
To augment the second list with the records on the first, Use the following statement:</p>
<p class="code">PLACE RECORDS ON [LIST] <span class="term">listname1</span> ON [LIST] <span class="term">listname2</span>
</p>
</p>
<p>If the second list was established earlier in the request, it now contains both sets of records, excluding duplications. If it was not, listname2 is a copy of listname1.</p>
<p>
====Removing a found set of records from a list====
If the second list was established earlier in the request, it now contains both sets of records, excluding duplications. If it was not, <var class="term">listname2</var> is a copy of <var class="term">listname1</var>.</p>  
<p>To remove listed records that match any in the set located by a labeled FIND statement, use the following statement: </p>
<p class="code">REMOVE RECORDS IN label FROM <var>[</var>LIST<var>]</var> listname
===Removing a found set of records from a list===
<p>
To remove listed records that match any in the set located by a labeled FIND statement, use the following statement: </p>
<p class="syntax">REMOVE RECORDS IN <span class="term">label</span> FROM [LIST] <span class="term">listname</span>
</p>
</p>
====Removing records from one list that appear on another list====
<p>To delete records from the second list if they match any on the first list, use this statement:</p>
===Removing records from one list that appear on another list===
<p class="code">REMOVE RECORDS ON <var>[</var>LIST<var>]</var> listname1
<p>
 
To delete records from the second list if they match any on the first list, use this statement:</p>
   FROM <var>[</var>LIST<var>]</var> listname2
<p class="syntax">REMOVE RECORDS ON [LIST] <span class="term">listname1</span>  
   FROM [LIST] <span class="term">listname2</span>
</p>
</p>
<p>The following request first creates a list of records that have a surcharge greater than 25%. Next, vehicles that are used for carpools are removed from the list. The list of those vehicles for which the premiums will be increased is then printed.</p>
<p>
<p class="code">BEGIN  
The following request first creates a list of records that have a surcharge greater than 25%. Next, vehicles that are used for carpools are removed from the list. The list of those vehicles for which the premiums will be increased is then printed.</p>
<p class="code">BEGIN
EXCESS.ACDT: IN VEHICLES FIND ALL RECORDS FOR WHICH
EXCESS.ACDT: IN VEHICLES FIND ALL RECORDS FOR WHICH
                 SURCHARGE% IS > 25
                 SURCHARGE% IS > 25
Line 110: Line 154:
                 PRINT VIN TAB OWNER POLICY TAB USAGE
                 PRINT VIN TAB OWNER POLICY TAB USAGE
             END FOR
             END FOR
END    
END
</p>
</p>
===Performing loops on lists of records===
<p>You can use a form of the FOR EACH RECORD statement to perform a record loop using a list. This form of FOR EACH RECORD begins a loop that is executed once for each record on the named list.     </p>
==Performing loops on lists of records==
<b>Syntax</b>
<p>
<p>The format of the FOR EACH RECORD statement is:</p>
You can use a form of the FOR EACH RECORD statement to perform a record loop using a list. This form of FOR EACH RECORD begins a loop that is executed once for each record on the named list. </p>
<p class="code">FOR {EACH | k} {RECORD | RECORDS}
 
====Syntax====
  [IN label | ON [LIST] listname]
<p>
 
The format of the FOR EACH RECORD statement is:</p>
  IN [ASCENDING | DESCENDING] ORDER
<p class="syntax">FOR {EACH | <span class="term">k</span>} {RECORD | RECORDS}  
 
  [IN label | ON [LIST] <span class="term">listname</span>]  
  [BY [EACH] fieldname] [FROM value1] [TO value2]
  IN [ASCENDING | DESCENDING] ORDER  
 
  [BY [EACH] <span class="term">fieldname</span>] [FROM <span class="term">value1</span>] [TO <span class="term">value2</span>]  
  [{WHERE |WITH} retrieval conditions]
  [{WHERE |WITH} <span class="term">retrieval-conditions</span>]
</p>
</p>
<p>where the options are the same as those for a record loop statement (see [[Record loops]]). </p>
<p>
<b>Example</b>
where the options are the same as those for a record loop statement (see [[Record loops]]). </p>
<p>If the following statements are added to [[#Creating and clearing a list|Creating and clearing a list]], the name, agent, and state for each person on list POLICIES is printed.</p>
====Example====
<p>
If the following statements are added to [[#Creating and clearing a list|Creating and clearing a list]], the name, agent, and state for each person on list POLICIES is printed.</p>
<p class="code">FOR EACH RECORD ON LIST POLICIES
<p class="code">FOR EACH RECORD ON LIST POLICIES
   PRINT FULLNAME WITH POLICY NO AT COLUMN 25 -
   PRINT FULLNAME WITH POLICY NO AT COLUMN 25 -
       WITH AGENT AT COLUMN 34 -
       WITH AGENT AT COLUMN 34 -
       WITH STATE AT COLUMN 50
       WITH STATE AT COLUMN 50
END FOR  
END FOR
</p>
</p>
<p>If there were no records on list POLICIES, the statements in the FOR EACH RECORD loop are not executed.   </p>
<p>
====Use of the IN ORDER clause====
If there were no records on list POLICIES, the statements in the FOR EACH RECORD loop are not executed. </p>
<p>When a FOR EACH RECORD ON LIST listname IN ORDER statement is used, a temporary copy of the list is created. Modifications made to the list from within the loop affect only the original list and thus do not affect the list resulting from the FOR statement.   </p>
===PLACE RECORD and REMOVE RECORD statements===
===Use of the IN ORDER clause===
<p>The record currently being processed within a loop can be placed on or removed from a list with the PLACE RECORD and REMOVE RECORD statements.</p>
<p>
<b>Syntax</b>
When a FOR EACH RECORD ON LIST listname IN ORDER statement is used, a temporary copy of the list is created. Modifications made to the list from within the loop affect only the original list and thus do not affect the list resulting from the FOR statement. </p>
<p class="code">PLACE RECORD ON <var>[</var>LIST<var>]</var> listname
==PLACE RECORD and REMOVE RECORD statements==
<p>
The record currently being processed within a loop can be placed on or removed from a list with the PLACE RECORD and REMOVE RECORD statements.</p>
====Syntax====
<p class="syntax">PLACE RECORD ON [LIST] <span class="term">listname</span>  


REMOVE RECORD FROM <var>[</var>LIST<var>]</var> listname   
REMOVE RECORD FROM [LIST] <span class="term">listname</span>
</p>
</p>
<p>The PLACE RECORD and REMOVE RECORD statements are supported for single records in remote file context. These statements are also supported in scattered group context.</p>
<p>
====Must be in a record loop====
The PLACE RECORD and REMOVE RECORD statements are supported for single records in remote file context. These statements are also supported in scattered group context.</p>
<p>The loop must be a record loop rather than a value loop (see the discussion on value loops in [[Value loops]]) and must loop on the records in a FIND statement, on a list, or in a SORT statement. </p>
<p>If the statement appears within a nested loop, the record currently being processed by the innermost loop is placed on or removed from the list.</p>
===Must be in a record loop===
====Timing for adding records====
<p>
<p>Exercise caution when adding records to a list while executing a loop governed by that list. If a record is added to the file before the current record being processed, the new record is not processed as part of the loop.   </p>
The loop must be a record loop rather than a value loop (see the discussion on value loops in [[Value loops]]) and must loop on the records in a FIND statement, on a list, or in a SORT statement. </p>
====Using group FINDs====
<p>
<p>Each list contains records from a particular file or group. Only records from that file or group can be placed on the list. If a list is created from a group FIND, records from an individual file FIND can only be added to the list if the file is a member of the group and if the IN GROUP MEMBER clause precedes the FIND statement.    </p>
If the statement appears within a nested loop, the record currently being processed by the innermost loop is placed on or removed from the list.</p>
<b>Example</b>
===Timing for adding records===
<p>
Exercise caution when adding records to a list while executing a loop governed by that list. If a record is added to the file before the current record being processed, the new record is not processed as part of the loop. </p>
===Using group FINDs===
<p>
Each list contains records from a particular file or group. Only records from that file or group can be placed on the list. If a list is created from a group FIND, records from an individual file FIND can only be added to the list if the file is a member of the group and if the IN GROUP MEMBER clause precedes the FIND statement.    </p>
====Example====
<p class="code">BEGIN
<p class="code">BEGIN
FIND.RECS: FIND ALL RECORDS FOR WHICH
FIND.RECS: FIND ALL RECORDS FOR WHICH
               RECTYPE = DRIVER
               RECTYPE = DRIVER
               SEX = F
               SEX = F
               DATE OF BIRTH IS LESS THAN 550101
               DATE OF BIRTH IS LESS THAN 19550101
           END FIND
           END FIND
           FOR EACH RECORD IN FIND.RECS
           FOR EACH RECORD IN FIND.RECS
Line 167: Line 229:
SORT.LIST: SORT RECORDS ON LIST A BY POLICY NO
SORT.LIST: SORT RECORDS ON LIST A BY POLICY NO
               FOR EACH RECORD IN SORT.LIST
               FOR EACH RECORD IN SORT.LIST
               PRINT FULLNAME WITH DATE OF BIRTH TO COLUMN 30
               PRINT FULLNAME WITH DATE OF BIRTH TO COLUMN 32
               PRINT POLICY NO
               PRINT POLICY NO
               SKIP 1 LINE
               SKIP 1 LINE
           END FOR
           END FOR
END  
END
</p>
</p>
<p>This request processes a list of records of female drivers with a date of birth before January 1, 1955 and who reside in California. (Refer to [[Flow of Control in User Language#IF statement|IF statement]] for a discussion.)</p>
<p>
===Using lists with FIND statements===
This request processes a list of records of female drivers with a date of birth before January 1, 1955 and who reside in California. (Refer to [[Flow of control in User Language#IF statement|IF statement]] for a discussion.)</p>  
====Creating sets of records from lists====
<p><var class="product">Model&nbsp;204</var> can create new sets of records from lists by using a variation of the FIND statement. This use of lists can simplify requests that must combine sets of records but that also must process them separately.     </p>
==Using lists with FIND statements==
<b>Syntax</b>
<p class="code">FIND ALL RECORDS ON <var>[</var>LIST<var>]</var> listname FOR WHICH  
===Creating sets of records from lists===
<p>
<var class="product">Model&nbsp;204</var> can create new sets of records from lists by using a variation of the FIND statement. This use of lists can simplify requests that must combine sets of records but that also must process them separately. </p>
====Syntax====
<p class="syntax">FIND ALL RECORDS ON [LIST] <span class="term">listname</span> FOR WHICH
</p>
</p>
<b>Example</b>
<p>The following request locates men who have incurred a type T3 incident and are either from California and have a date of birth greater than 600101 or are from Colorado and have a date of birth greater than 620101.</p>
====Example====
<p>
The following request locates men who have incurred a type T3 incident and are either from California and have a date of birth greater than 19600101 or are from Colorado and have a date of birth greater than 19620101.</p>
<p class="code">BEGIN
<p class="code">BEGIN
CALIF.MALES:  FIND ALL RECORDS FOR WHICH
CALIF.MALES:  FIND ALL RECORDS FOR WHICH
                   SEX = M
                   SEX = M
                   STATE = CALIFORNIA
                   STATE = CALIFORNIA
                   DATE OF BIRTH IS > 600101
                   DATE OF BIRTH IS > 19600101
               END FIND
               END FIND
COLO.MALES:    FIND ALL RECORDS FOR WHICH
COLO.MALES:    FIND ALL RECORDS FOR WHICH
                   SEX = M
                   SEX = M
                   STATE = COLORADO
                   STATE = COLORADO
                   DATE OF BIRTH IS > 620101
                   DATE OF BIRTH IS > 19620101
               END FIND
               END FIND
               PLACE RECORDS IN CALIF.MALES ON LIST TOTAL
               PLACE RECORDS IN CALIF.MALES ON LIST TOTAL
Line 202: Line 271:
                     WITH DATE OF BIRTH AT COLUMN 30
                     WITH DATE OF BIRTH AT COLUMN 30
               END FOR
               END FOR
END  
END
</p>
</p>
====Using the LIST$ condition====
<b>Description</b>
===Using the LIST$ condition===
<p>You can refer to the collection of records on a list by entering LIST$ as a condition in a FIND statement. </p>
<b>Syntax</b>
====Description====
<p class="code">LIST$ listname  
<p>
You can refer to the collection of records on a list by entering LIST$ as a condition in a FIND statement. </p>
====Syntax====
<p class="syntax">LIST$ <span class="term">listname</span>
</p>
</p>
<b>Example</b>
====Example====
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
<p class="code">FIND.RECS: FIND ALL RECORDS FOR WHICH
               LIST$ ALPHA OR LIST$ BETA
               LIST$ ALPHA OR LIST$ BETA
               SEX = FEMALE
               SEX = FEMALE
               NOT LIST$ GAMMA
               NOT LIST$ GAMMA
           END FIND  
           END FIND
</p>
</p>
<p>In this example, the FIND.RECS statement retrieves records of persons who are female and who are on either list ALPHA or BETA but not on list GAMMA. </p>
<p>
In this example, the FIND.RECS statement retrieves records of persons who are female and who are on either list ALPHA or BETA but not on list GAMMA. </p>
<!-- /div --> <!-- end of toc limit div -->
 
[[Category:SOUL]]
[[Category:SOUL]]

Latest revision as of 22:40, 18 October 2017


Overview

The set of records retrieved by the FIND statement cannot be modified, except from within a record loop. However, a found record set can be copied onto the your own named list and that list then can be modified by using a special set of User Language statements. The resulting list can be accessed by any statement that normally refers to a FIND statement.

Model 204 can repeat a series of nested statements against a predefined list of records. Record loops can be executed once for each record in a list and new lists can be generated. This page identifies the statements used to create, maintain, and loop on a list of records.

Creating and clearing a list

You can create a list in one of two ways:

  • By referring to a list with a PLACE RECORDS IN statement
  • By explicitly declaring a list using a form of the DECLARE statement

You can create a list using this statement:

Syntax

PLACE RECORDS IN label ON [LIST] listname

The PLACE RECORDS IN statement is supported in scattered group context.

Example

This request demonstrates the use of the PLACE RECORDS IN statement:

BEGIN CARPOOLERS: FIND ALL RECORDS FOR WHICH USAGE = CARPOOL END FIND FOR EACH RECORD IN CARPOOLERS DRIVER: NOTE PRINCIPAL DRIVER NO.CP: FIND ALL RECORDS FOR WHICH PRINCIPAL DRIVER = VALUE IN DRIVER USAGE = NOT CARPOOL END FIND CREATE.LIST: PLACE RECORDS IN NO.CP ON LIST OTHERCAR END FOR LIST.CT: COUNT RECORDS ON LIST OTHERCAR PRINT.CT: PRINT COUNT IN LIST.CT END

The CREATE.LIST statement creates a list of records. During each repetition of the FOR EACH RECORD loop, records are added to the list. The total number is then counted by the LIST.CT statement and printed by the PRINT.CT statement.

List names

A list must have a name, like OTHERCAR in the example above. The list name is made up of a string of alphanumeric characters as many as 255 characters in length.

More than one list can be used in a request, but each must have a distinct name.

DECLARE LIST syntax

You can also create a list by using this form of the DECLARE statement:

DECLARE LIST listname [IN [FILE |[PERM | TEMP] GROUP] filename] [AT location] [COMMON | GLOBAL]

If a list is not declared, it is created when it is first referenced, for example, with a PLACE RECORDS statement. Declaring %variables and %variable arrays discusses the DECLARE statement in detail.

The DECLARE LIST statement is supported in remote file and scattered group contexts.

Duration of a list

Once it is created, you can refer to any list for the duration of the request. Lists which have not been declared GLOBAL are automatically cleared at the beginning of a request, so that no records listed in previous requests remain. Global lists are stored for reference by future requests. See Global features for more information on global found sets and lists.

A list created during a request that ends with END MORE is stored for future use by requests that begin with MORE, even if the list was not originally declared GLOBAL (see Large request considerations).

Unique inclusion of records on a list

Each record appears only once on a list, even if it is placed there repeatedly. Therefore lists can be used to eliminate redundancies in multiple sets of records. Consider this example:

BEGIN CAL.POL.HLDR: IN CLIENTS FIND ALL RECORDS FOR WHICH RECTYPE= POLICYHOLDER STATE = CALIFORNIA END FIND PLACE RECORDS IN CAL.POL.HLDR ON LIST POLICIES GOODRICH: IN CLIENTS FIND ALL RECORDS FOR WHICH AGENT = GOODRICH END FIND PLACE RECORDS IN GOODRICH ON LIST POLICIES . . .

Records of California policy holders, or records for which the agent is Goodrich, are found by this request. Although some records can satisfy both of these conditions, they appear on the list only once. However, the user can still access each set of records separately by referring back to their corresponding FIND labels.

Clearing a list

This statement removes all records from the named list:

CLEAR LIST listname

If the CLEAR LIST statement is the first reference to the named list in the request, then CLEAR LIST creates and initializes the named list.

The CLEAR LIST statement normally clears an existing list; no IN clause is required. When a CLEAR LIST statement appears in a request before the first reference to the list, an IN clause might be necessary to create the list in the same context as the later references. References to an existing set of records in the CLEAR LIST or FIND statement override the IN clause.

The CLEAR LIST statement is supported in remote file and scattered group contexts.

You can use the IN GROUP MEMBER clause to restrict the CLEAR LIST to one member of a group. For more information, see IN GROUP MEMBER clause.

Maintaining lists

User Language supplies three statements that provide the means to copy, augment, and edit lists.

For a discussion of adding and deleting records from a list from within a record loop, refer to PLACE RECORD and REMOVE RECORD statements.

Records from sorted sets

Lists that contain records from sorted sets are not maintained in sorted order. However, you can explicitly sort any list.

Adding one list to another

To augment the second list with the records on the first, Use the following statement:

PLACE RECORDS ON [LIST] listname1 ON [LIST] listname2

If the second list was established earlier in the request, it now contains both sets of records, excluding duplications. If it was not, listname2 is a copy of listname1.

Removing a found set of records from a list

To remove listed records that match any in the set located by a labeled FIND statement, use the following statement:

REMOVE RECORDS IN label FROM [LIST] listname

Removing records from one list that appear on another list

To delete records from the second list if they match any on the first list, use this statement:

REMOVE RECORDS ON [LIST] listname1 FROM [LIST] listname2

The following request first creates a list of records that have a surcharge greater than 25%. Next, vehicles that are used for carpools are removed from the list. The list of those vehicles for which the premiums will be increased is then printed.

BEGIN EXCESS.ACDT: IN VEHICLES FIND ALL RECORDS FOR WHICH SURCHARGE% IS > 25 END FIND PLACE RECORDS IN EXCESS.ACDT ON LIST CHECK CARPOOLERS: FIND ALL RECORDS ON LIST CHECK FOR WHICH USAGE = CARPOOL END FIND REMOVE RECORDS IN CARPOOLERS FROM LIST CHECK SET HEADER 1 'PREMIUMS TO BE INCREASED' - AT COLUMN 10 SET HEADER 3 'VEHICLE ID' TAB 'POLICY' - TAB 'USAGE' SET HEADER 4 NEW PAGE FOR EACH RECORD ON LIST CHECK PRINT VIN TAB OWNER POLICY TAB USAGE END FOR END

Performing loops on lists of records

You can use a form of the FOR EACH RECORD statement to perform a record loop using a list. This form of FOR EACH RECORD begins a loop that is executed once for each record on the named list.

Syntax

The format of the FOR EACH RECORD statement is:

FOR {EACH | k} {RECORD | RECORDS} [IN label | ON [LIST] listname] IN [ASCENDING | DESCENDING] ORDER [BY [EACH] fieldname] [FROM value1] [TO value2] [{WHERE |WITH} retrieval-conditions]

where the options are the same as those for a record loop statement (see Record loops).

Example

If the following statements are added to Creating and clearing a list, the name, agent, and state for each person on list POLICIES is printed.

FOR EACH RECORD ON LIST POLICIES PRINT FULLNAME WITH POLICY NO AT COLUMN 25 - WITH AGENT AT COLUMN 34 - WITH STATE AT COLUMN 50 END FOR

If there were no records on list POLICIES, the statements in the FOR EACH RECORD loop are not executed.

Use of the IN ORDER clause

When a FOR EACH RECORD ON LIST listname IN ORDER statement is used, a temporary copy of the list is created. Modifications made to the list from within the loop affect only the original list and thus do not affect the list resulting from the FOR statement.

PLACE RECORD and REMOVE RECORD statements

The record currently being processed within a loop can be placed on or removed from a list with the PLACE RECORD and REMOVE RECORD statements.

Syntax

PLACE RECORD ON [LIST] listname REMOVE RECORD FROM [LIST] listname

The PLACE RECORD and REMOVE RECORD statements are supported for single records in remote file context. These statements are also supported in scattered group context.

Must be in a record loop

The loop must be a record loop rather than a value loop (see the discussion on value loops in Value loops) and must loop on the records in a FIND statement, on a list, or in a SORT statement.

If the statement appears within a nested loop, the record currently being processed by the innermost loop is placed on or removed from the list.

Timing for adding records

Exercise caution when adding records to a list while executing a loop governed by that list. If a record is added to the file before the current record being processed, the new record is not processed as part of the loop.

Using group FINDs

Each list contains records from a particular file or group. Only records from that file or group can be placed on the list. If a list is created from a group FIND, records from an individual file FIND can only be added to the list if the file is a member of the group and if the IN GROUP MEMBER clause precedes the FIND statement.

Example

BEGIN FIND.RECS: FIND ALL RECORDS FOR WHICH RECTYPE = DRIVER SEX = F DATE OF BIRTH IS LESS THAN 19550101 END FIND FOR EACH RECORD IN FIND.RECS IF STATE = 'CALIFORNIA' THEN PLACE RECORD ON LIST A END IF END FOR SORT.LIST: SORT RECORDS ON LIST A BY POLICY NO FOR EACH RECORD IN SORT.LIST PRINT FULLNAME WITH DATE OF BIRTH TO COLUMN 32 PRINT POLICY NO SKIP 1 LINE END FOR END

This request processes a list of records of female drivers with a date of birth before January 1, 1955 and who reside in California. (Refer to IF statement for a discussion.)

Using lists with FIND statements

Creating sets of records from lists

Model 204 can create new sets of records from lists by using a variation of the FIND statement. This use of lists can simplify requests that must combine sets of records but that also must process them separately.

Syntax

FIND ALL RECORDS ON [LIST] listname FOR WHICH

Example

The following request locates men who have incurred a type T3 incident and are either from California and have a date of birth greater than 19600101 or are from Colorado and have a date of birth greater than 19620101.

BEGIN CALIF.MALES: FIND ALL RECORDS FOR WHICH SEX = M STATE = CALIFORNIA DATE OF BIRTH IS > 19600101 END FIND COLO.MALES: FIND ALL RECORDS FOR WHICH SEX = M STATE = COLORADO DATE OF BIRTH IS > 19620101 END FIND PLACE RECORDS IN CALIF.MALES ON LIST TOTAL PLACE RECORDS IN COLO.MALES ON LIST TOTAL T3.INCIDENTS: FIND ALL RECORDS ON LIST TOTAL FOR WHICH INCIDENT = T3 END FIND FOR EACH RECORD IN T3.INCIDENTS PRINT FULLNAME - WITH DATE OF BIRTH AT COLUMN 30 END FOR END

Using the LIST$ condition

Description

You can refer to the collection of records on a list by entering LIST$ as a condition in a FIND statement.

Syntax

LIST$ listname

Example

FIND.RECS: FIND ALL RECORDS FOR WHICH LIST$ ALPHA OR LIST$ BETA SEX = FEMALE NOT LIST$ GAMMA END FIND

In this example, the FIND.RECS statement retrieves records of persons who are female and who are on either list ALPHA or BETA but not on list GAMMA.