Reading From a Data Source

In this section:

Repositioning Your Location in a Data Source

Most applications need to read data from a data source. The most common method is to read data from a data source into a data source stack. Before reading, you first need to select the record in which the data resides. There are five ways of selecting records:

By field value for an entire set of records. Use the NEXT command. The WHERE phrase enables you to select by value, and the FOR ALL phrase selects the entire set of records that satisfy the WHERE selection condition. The basic syntax for this is:
```
FOR ALL NEXT fields INTO stack WHERE selection_condition;
```

By field value for a sequence (subset) of records. Use the NEXT command. This is similar to the technique for a set of records, except that it employs the FOR n phrase, selecting, at the current position in the data source, the first n records that satisfy the WHERE condition. The basic syntax for this is:
```
FOR n NEXT fields INTO stack WHERE selection_condition;
```

By field value, one segment at a time, one record at a time. Use the MATCH command. The basic syntax for this is:
```
MATCH fields [FROM stack] [INTO stack];
```

Sequentially for a sequence (subset) of records. Use the NEXT command. This technique employs the FOR n phrase to select the next n records. The basic syntax for this is:
```
FOR n NEXT fields INTO stack;
```

Sequentially, one segment instance at a time, one record at a time. Use the NEXT command. The basic syntax for this is:
```
NEXT fields [INTO stack];
```

You can read from individual data sources, and from those that have been joined. Maintain Data supports joins that are defined in a Master File. For information about defining joins in a Master File, see the Describing Data With WebFOCUS Language manual. Maintain Data can read from joined data sources, but cannot write to them.

You can evaluate the success of a command that reads from a data source by testing the FocError system variable, as described in Evaluating the Success of a Simple Data Source Command.

The NEXT and MATCH commands are described in detail in Command Reference in the App Studio Maintain Data Language Reference manual.

Repositioning Your Location in a Data Source

Each time you issue a NEXT command, Maintain Data begins searching for records from the current position in the data source. For example, if your first data source operation retrieved a set of records

FOR ALL NEXT CustID INTO SmokeStack
    WHERE ProdName EQ 'VCR DUST COVER';

then Maintain Data will have searched sequentially through the entire data source, so the current position marker will now point to the end of the data source. If you then issue another NEXT command

FOR ALL NEXT LastName FirstName INTO CandyStack
    WHERE ProdName EQ 'CANDY';

Maintain Data searches from the current position to the end of the data source. Since the current position is the end of the data source, no records are retrieved.

When you want a NEXT command to search through the entire data source (as is often the case when you wish to retrieve a set of records) you should first issue the REPOSITION command to move the current position marker to the beginning of the data source.

Example: Repositioning to the Beginning of the Data Source

The following REPOSITION command specifies the CustID field in the root segment, and so moves the current position marker for the root segment chain and all of its descendant chains back to the beginning of the chain (in effect, back to the beginning of the data source):

REPOSITION CustID;
FOR ALL NEXT LastName FirstName INTO CandyStack 
    WHERE ProdName EQ 'CANDY';