Lists

div class="toclimit-3"

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 PRINCIPLE DRIVER NO.CP: FIND ALL RECORDS FOR WHICH PRINCIPLE 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. Flow of control in User Language 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.