OBTAIN
operand1
|
For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.
Belongs to Function Group: Reporting Mode Statements
This document covers the following topics:
The OBTAIN statement is used in reporting mode to cause one or more fields
to be read from a file. The OBTAIN statement does not generate any executable
code in the Natural object program. It is primarily used to read a range of values of a
multiple-value field or a range of occurrences of a periodic group so that portions of
these ranges may be subsequently referenced in the program.
An OBTAIN statement is not required for each database field to be
referenced in the program since Natural automatically reads each database field referenced
in a subsequent statement (for example, a DISPLAY or COMPUTE statement).
When multiple-value or periodic-group fields in the form of an array are referenced, the
array must be defined with an OBTAIN statement to ensure that it is built for
all occurrences of the fields. If individual multiple-value or periodic-group fields are
referenced before the array is defined, the fields will not be placed within the array and
will exist independent of the array. The fields will contain the same value as the
corresponding occurrence within the array.
Individual occurrences of multiple-value or periodic-group fields or subarrays can be held within a previously defined array if the array dimensions of the second individual occurrence or array are contained within the initial array.
References to multiple-value or periodic-group fields with unique variable index cannot be contained in an array of values. If individual occurrences of an array are to be processed with a variable index, the index expression must be prefixed with the unique variable index to denote the individual array.
The OBTAIN statement is for reporting mode only.
Operand Definition Table:
| Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operand1
|
S | A | G | A | U | N | P | I | F | B | D | T | L | yes | yes | |||||
Syntax Element Description:
| Syntax Element | Description |
|---|---|
operand1
|
Fields to be Read:
With |
READ FINANCE OBTAIN CREDIT-CARD (1-10) DISPLAY CREDIT-CARD (3-5) CREDIT-CARD (6-8) SKIP 1 END
The above example results in the first 10 occurrences of the field
CREDIT-CARD (which is contained in a periodic group) being read and
occurrences 3-5 and 6-8 being displayed where the subsequent subarrays will reside in the
initial array (1-10).
READ FINANCE MOVE 'ONE' TO CREDIT-CARD (1) DISPLAY CREDIT-CARD (1) CREDIT-CARD (1-5)
Output:
CREDIT-CARD CREDIT-CARD
------------------ ----------------
ONE DINERS CLUB
AMERICAN EXPRESS
ONE AVIS
AMERICAN EXPRESS
ONE HERTZ
AMERICAN EXPRESS
ONE UNITED AIR TRAVEL
The first reference to CREDIT-CARD (1) is not contained within the array.
The array which is defined after the reference to the unique occurrence (1) cannot
retroactively include a unique occurrence or an array which is shorter than the one being
defined.
READ FINANCE OBTAIN CREDIT-CARD (1-5) MOVE 'ONE' TO CREDIT-CARD (1) DISPLAY CREDIT-CARD (1) CREDIT-CARD (1-5)
Output:
CREDIT-CARD CREDIT-CARD
------------------ ----------------
ONE ONE
AMERICAN EXPRESS
ONE ONE
AMERICAN EXPRESS
ONE ONE
AMERICAN EXPRESS
ONE ONE
The individual reference to CREDIT-CARD (1) is contained within the array
defined in the OBTAIN statement.
MOVE (1) TO INDEX READ FINANCE DISPLAY CREDIT-CARD (1-5) CREDIT-CARD (INDEX)
Output:
CREDIT-CARD CREDIT-CARD ------------------- ---------------- DINERS CLUB DINERS CLUB AMERICAN EXPRESS AVIS AVIS AMERICAN EXPRESS HERTZ HERTZ AMERICAN EXPRESS UNITED AIR TRAVEL UNITED AIR TRAVEL
The reference to CREDIT-CARD using the variable index notation is not contained
within the array.
RESET A(A20) B(A20) C(A20) MOVE 2 TO I (N3) MOVE 3 TO J (N3) READ FINANCE OBTAIN CREDIT-CARD (1:3) CREDIT-CARD (I:I+2) CREDIT-CARD (J:J+2) FOR K (N3) = 1 TO 3 MOVE CREDIT-CARD (1.K) TO A MOVE CREDIT-CARD (I.K) TO B MOVE CREDIT-CARD (J.K) TO C DISPLAY A B C LOOP /* FOR LOOP / * READ END
Output:
A B C ------------------- ------------------- ------------------- CARD 01 CARD 02 CARD 03 CARD 02 CARD 03 CARD 04 CARD 03 CARD 04 CARD 05
The three arrays may be accessed individually by using the unique base index as qualifier for the index expression.
READ FINANCE OBTAIN CREDIT-CARD (1-10) FOR I 1 10 MOVE CREDIT-CARD (I) TO A(A20) WRITE A END
The above example will produce error message NAT1006 (value for variable index = 0)
because, at the time the record is read (READ), the index I
still contains the value 0.
In any case, the above example would not have printed the first 10 occurrences of
CREDIT-CARD because the individual occurrence with the variable index
cannot be contained in the array and the variable index (I) is only evaluated
when the next record is read.
The following is the correct method of performing the above:
READ FINANCE OBTAIN CREDIT-CARD (1-10) FOR I 1 10 MOVE CREDIT-CARD (1.I) TO A (A20) WRITE A END
READ FINANCE FOR I 1 10 WRITE CREDIT-CARD (I) END
The above example will produce error message NAT1006 because the index I is
zero when the record is read in the READ
statement.
The following is the correct method of performing the above:
READ FINANCE FOR I 1 10 GET SAME WRITE CREDIT-CARD (0030/I) END
The GET SAME statement is necessary
to reread the record after the variable index has been updated in the FOR loop.
** Example 'OBTEX1': OBTAIN
************************************************************************
RESET #INDEX (I1)
*
LIMIT 5
READ EMPLOYEES BY CITY
OBTAIN SALARY (1:4)
/*
IF SALARY (4) GT 0 DO
WRITE '=' NAME / 'SALARIES (1:4):' SALARY (1:4)
FOR #INDEX 1 TO 4
WRITE 'SALARY' #INDEX SALARY (1.#INDEX)
LOOP
SKIP 1
DOEND
LOOP
*
END
Page 1 05-02-08 13:37:48
NAME: SENKO
SALARIES (1:4): 31500 29900 28100 26600
SALARY 1 31500
SALARY 2 29900
SALARY 3 28100
SALARY 4 26600
NAME: HAMMOND
SALARIES (1:4): 22000 20200 18700 17500
SALARY 1 22000
SALARY 2 20200
SALARY 3 18700
SALARY 4 17500
** Example 'OBTEX2': OBTAIN (with multiple ranges)
************************************************************************
RESET #INDEX (I1) #K (I1)
*
#INDEX := 2
#K := 3
*
LIMIT 2
*
READ EMPLOYEES BY CITY
OBTAIN SALARY (1:5)
SALARY (#INDEX:#INDEX+3)
/*
IF SALARY (5) GT 0 DO
WRITE '=' NAME
WRITE 'SALARIES (1-5):' SALARY (1:5) /
WRITE 'SALARIES (2-5):' SALARY (#INDEX:#INDEX+3)
WRITE 'SALARIES (2-5):' SALARY (#INDEX.1:4) /
WRITE 'SALARY 3:' SALARY (3)
WRITE 'SALARY 3:' SALARY (#K)
WRITE 'SALARY 4:' SALARY (#INDEX.#K)
DOEND
LOOP
Page 1 05-02-08 13:38:31
NAME: SENKO
SALARIES (1-5): 31500 29900 28100 26600 25200
SALARIES (2-5): 29900 28100 26600 25200
SALARIES (2-5): 29900 28100 26600 25200
SALARY 3: 28100
SALARY 3: 28100
SALARY 4: 26600
For further examples of using the OBTAIN statement, see Referencing a Database
Array in the Programming Guide.