BEG AT

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.

    ••••• BEG AT   ••• •••••••• •• ••• •••••••••••••••••••••• •••
    (1)            (2) (3)      (4)(5) (6)                    (7)

Using the Statement

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.

Restrictions

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 file’s key, a field that is part of the file’s key, or a field that is the same domain-type as the file’s key. In any case, set the field’s content to the desired starting value before executing the BEG AT statement.

You cannot use the BEG AT statement with one-record files.

Related Statements

BEG READ, END AT, END READ, READNEXT

Examples

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.

          BEG AT   TAR TRANFILE IN TAR CUSTOMER ID
          END AT   TAR TRANFILE IN TAR CUSTOMER ID
          BEG READ TAR TRANFILE               HOLD 0 KEY IS  TRANFILE KEY
          *
          *        (Process each TRANFILE record for specified customer)
          *
          END READ TAR TRANFILE

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:

          BEG AT   TAR ORDER    IN TAR TRANFILE CUSTOMER ID
          END AT   TAR ORDER    IN TAR TRANFILE CUSTOMER ID
          LABEL    :NEXT ORDER RECORD
          READNEXT TAR ORDER                  HOLD 0 FT 0 BY ORDER CUST ID
    T     ...      (Process each order record for specified customer)
    T     GOTO     :NEXT ORDER RECORD
          *
          *        (Terminate order processing for specified customer)

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.