END AT

The END AT statement is used in conjunction with a BEG READ/END READ loop, or a READNEXT statement, and may optionally be used in conjunction with a BEG AT statement. END AT specifies the ending key value for a range of records to be read.

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

Using the Statement

The key used to access records in the file is specified in the subsequent BEG READ or READNEXT statement if the file is an indexed file. If the file is sequential, the key field for BEG READ or READNEXT must be blank, and the field used in the END AT statement must be numeric.

The END AT statement specifies an application ID and file name to identify the file upon which the range is being specified, and which is read in the subsequent BEG READ or READNEXT. The field specified by END AT must contain the ending value of the key of the last record that is to be read or, if the file is a sequential file, the record number of the last record to be read.

A relation is specified to indicate whether to end at a record with a key that includes (IN) or excludes (EX) the specified value.

END AT temporarily saves the contents of the specified field and, if the file is indexed, its length. If this length is less than the key length used in a subsequent BEG READ or READNEXT statement, only the leading portion of the key is constrained. In other words, the field value is padded with HEX FFs if the relation is IN, or with HEX 00s if the relation is EX. If this length is longer than the key specified in the subsequent BEG READ or READNEXT, the extra characters are ignored.

Since END AT saves the contents of the specified field regardless of field type or format, the field must exactly match the field type and format of the field used to access the file in a subsequent BEG READ or READNEXT statement. For example, if the key in the subsequent BEG READ statement is a binary numeric field with nine digits, you should not use a seven-digit numeric field or a packed decimal numeric field in the END AT statement to set the starting value. Again, this applies only to indexed files; sequential files can specify any valid record number.

Note that any field, including non-key fields, can be used with the END AT statement. This statement uses the contents of the field as an end marker. Unless the file is sequential, constant fields are assumed to be alphanumeric; for sequential files, constants are assumed to be numeric. The length of the alphanumeric constant is determined by discarding all trailing blanks; hence, an all-blank constant results in a length of zero and causes a subsequent BEG READ or READNEXT to include all of the records through the end of the file, regardless of the relation (IN or EX).

Restrictions

If an END AT is not executed before a BEG READ statement, records are read through the end of the file. If an END AT is not executed before a READNEXT statement, the READNEXT is successful unless an end-of-file condition is encountered.

If an END AT is followed by a BEG AT for the same file, the ending key value is lost.

The END AT statement cannot be used with one-record files.

Related Statements

BEG AT, BEG READ, END READ, READNEXT

Example

The following example uses END AT (with BEG 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, the 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 ending range, no statements within the BEG READ, END READ are executed.

The next example shows END 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.