BEG AT specifies the starting key value for a range of records to be read from a file. You may use a BEG AT preceding a BEG READ/END READ loop, or before a READNEXT statement. If you want to specify the ending value for the range, you also include an END AT statement following a BEG AT.
(1) (2) (3) (4)(5) (6) (7)
(6) Field name
(3) File name
(4) Relation (IN,EX)
When using a BEG AT statement, you specify a relation to indicate whether to start at a record with a key that includes (IN) or excludes (EX) the specified value.
Note that you can specify any field, including a non-key field, in the BEG AT statement. If you specify a constant, it is assumed to be an alpha-type constant unless the file is sequential, in which case the value is assumed to be a numeric-type constant. The length of the alpha-type constant is determined by discarding all trailing blanks; hence, an all-blank constant will result in a length of zero, and will cause a subsequent BEG READ or READNEXT to position to the first record in the file, regardless of the relation (IN or EX).
If a BEG READ is not preceded by a BEG AT statement, records will be read from the beginning of the file. If a READNEXT is not preceded by a BEG AT statement, records are read from the current position in the file.
If the file to be read is sequential, the field used in the BEG AT statement must refer to a numeric domain, and the key field for the BEG READ or READNEXT statement must be blank.
Since BEG AT saves the contents of the specified field regardless of the field-type or format, the field must match the field-type and format of the key field used to access the file in a subsequent BEG READ or READNEXT statement. For example, if the key field in the subsequent BEG READ statement is a binary numeric field with nine digits, you cannot use a seven-digit numeric field or a packed-decimal numeric field in the BEG AT statement to set the starting value. This applies only to indexed files; for sequential files, any numeric field can be specified.
To ensure that the format of the field specified in the BEG AT is appropriate, use either the specified files key, a field that is part of the files key, or a field that is the same domain-type as the files key. In any case, set the fields content to the desired starting value before executing the BEG AT statement.
You cannot use the BEG AT statement with one-record files.
BEG READ, END AT, END READ, READNEXT
The following example uses BEG AT (with END AT) to specify a range of records to be read in the file specified in the subsequent BEG READ statement. The example includes a transaction file of records to be posted to the master (CUSTOMER) file. The first part of the key to the transaction file is the customer ID. You want to restrict the reading of the transaction file to only the range of record keys that includes a specific customer ID.
The preceding example processes records on the TRANFILE file with a key value within the range specified by the BEG AT/END AT pair of statements. If the END AT is not included, processing continues until the end of the file is reached. When used with BEG READ, and there are no records on the file that meet the specified starting range criteria, no statements within the BEG READ, END READ are executed.
The next example shows BEG AT used preceding a READNEXT statement:
In this example, if the ORDER file contains one or more records matching the specified customer ID, the true/false status indicator is set to T by the READNEXT statement.