OBTAIN

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:


Function

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.

Restriction

The OBTAIN statement is for reporting mode only.

Syntax Description

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 operand1 you specify the field(s) to be made available as a result of the OBTAIN statement.

Examples:

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.

Invalid Example 1

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

Invalid Example 2

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.

Examples

Example 1 - OBTAIN Statement

** 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

Output of Program OBTEX1:

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 2 - OBTAIN Statement with Multiple Ranges

** 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

Output of Program OBTEX2:

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.