CALL FILE

Structured Mode Syntax

CALL FILE 'program-name' operand1 operand2
   statement ../graphics/dot3.gif
END-FILE

Reporting Mode Syntax

CALL FILE 'program-name' operand1 operand2
   statement ../graphics/dot3.gif
LOOP

This document covers the following topics:

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Related Statements: CALL | CALL LOOP | CALLNAT | DEFINE SUBROUTINE | ESCAPE | FETCH | PERFORM

Belongs to Function Group: Invoking Programs and Routines


Function

The CALL FILE statement is used to call a non-Natural program which reads a record from a non-Adabas file and returns the record to the Natural program for processing.

Restriction

The statements AT BREAK, AT START OF DATA and AT END OF DATA must not be used within a CALL FILE processing loop.

Syntax Description

Operand Definition Table:

Operand Possible Structure Possible Formats Referencing Permitted Dynamic Definition
operand1   S A     A U N P I F B D T L C     yes yes
operand2   S A G   A U N P I F B D T L C     yes yes

Syntax Element Description:

Syntax Element Description
'program-name'
Program to be Called:

The name of the non-Natural program to be called.

The length of the program name should be 1 to 8.

operand1
Control Field:
operand1 is used to provide control information.
operand2
Record Area:
operand2 defines the record area.

The format of the record to be read can be described using field definitions (or FILLER nX) entries following the name of the first field in the record. The fields used to define the record format must not have been previously defined in the Natural program. This ensures that fields are allocated in the contiguous storage by Natural.

statement ...
Processing Loop:
The CALL FILE statement initiates a processing loop which must be terminated with an ESCAPE or STOP statement. More than one ESCAPE statement may be specified to escape from a CALL FILE loop based on different conditions.
END-FILE
End of CALL FILE Statement:

In structured mode, the Natural reserved keyword END-FILE must be used to end the CALL FILE statement.

In reporting mode, the Natural statement LOOP is used to end the CALL FILE statement.

LOOP

Example

Calling Program:

** Example 'CFIEX1': CALL FILE                                          
************************************************************************
DEFINE DATA LOCAL                                                       
1 #CONTROL (A3)                                                         
1 #RECORD                                                               
  2 #A     (A10)                                                        
  2 #B     (N3.2)                                                       
  2 #FILL1 (A3)                                                         
  2 #C     (P3.1)                                                       
END-DEFINE                                                              
*                                                                       
CALL FILE 'USER1' #CONTROL #RECORD                                      
  IF #CONTROL = 'END'                                                   
    ESCAPE BOTTOM                                                       
  END-IF                                                                
END-FILE                                                                
/*****************************                                          
/* ... PROCESS RECORD ...                                               
/*****************************                                          
END

The byte layout of the record passed by the called program to the Natural program in the above example is as follows:

CONTROL #A       #B   FILLER  #C
(A3)   (A10)   (N3.2)  3X   (P3.1)
  
xxx xxxxxxxxxx xxxxx   xxx   xxx

Called COBOL Program:

ID DIVISION.
PROGRAM-ID. USER1.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
     SELECT USRFILE ASSIGN UT-S-FILEUSR.
DATA DIVISION.
FILE SECTION.
FD   USRFILE RECORDING F LABEL RECORD OMITTED
     DATA RECORD DATA-IN.
01   DATA-IN         PIC X(80).
LINKAGE SECTION.
01   CONTROL-FIELD   PIC XXX.
01   RECORD-IN       PIC X(21).
PROCEDURE DIVISION USING CONTROL-FIELD RECORD-IN.
BEGIN.
     GO TO FILE-OPEN.
FILE-OPEN.
     OPEN INPUT USRFILE
     MOVE SPACES TO CONTROL-FIELD.
     ALTER BEGIN TO PROCEED TO FILE-READ.
FILE-READ.
     READ USRFILE INTO RECORD-IN
          AT END
          MOVE 'END' TO CONTROL-FIELD
          CLOSE USRFILE
          ALTER BEGIN TO PROCEED TO FILE-OPEN.
     GOBACK.