FETCH

FETCH

REPEAT
RETURN

operand1 [operand2 [(parameter)]]

This document covers the following topics:

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

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

Belongs to Function Group: Invoking Programs and Routines


Function

The FETCH statement is used to execute a Natural object program written as a main program. The program to be loaded must have been previously stored in the Natural system file with a CATALOG or STOW command. Execution of the FETCH statement does not overwrite any source program in the Natural source work area.

For Natural RPC: See Notes on Natural Statements on the Server (in the Natural RPC (Remote Procedure Call) documentation).

Additional Considerations

In addition to the parameters passed explicitly with FETCH, the fetched program also has access to the established global data area.

The FETCH statement may cause the internal execution of an END TRANSACTION statement based on the setting of the Natural profile parameter OPRB (Database Open/Close Processing) as set by the Natural administrator. If a logical transaction is to span multiple Natural programs, the Natural administrator should be consulted to ensure that the OPRB parameter is set correctly.

Syntax Description

Operand Definition Table:

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

Syntax Element Description:

Syntax Element Description
REPEAT
REPEAT Option:

The REPEAT option causes Natural to suppress the prompt for user input for each INPUT statement issued during the execution of the FETCHed program. It may be used to send information about the execution of the program to the terminal without the user having to reply with ENTER.

RETURN
RETURN Option:

Without the specification of RETURN, the execution of the program issuing the FETCH statement will be terminated immediately and the fetched program will be activated as a "main program" (Level 1).

If a program is invoked with FETCH RETURN, the execution of the invoking program will be suspended - not terminated - and the FETCHed program will be activated as a "subordinate program" on a higher level. Control is returned to the invoking program when an END or ESCAPE ROUTINE statement is encountered in the FETCHed program. Processing is continued with the statement following the FETCH RETURN statement.

operand1
Program Name:

The name of the program module (maximum 8 characters) can be specified as an alphanumeric constant or the content of an alphanumeric variable of length 1 to 8. The case of the specified name is not translated.

Natural will attempt to locate the program in the library currently active at the time the FETCH statement is issued. If the program is not found, Natural will attempt to locate the program in the steplibs. If the program is still not found, an error message will be issued.

The program name may contain an ampersand (&); at execution time, this character will be replaced by the one-character code corresponding to the current value of the system variable *LANGUAGE. This makes it possible, for example, to invoke different programs for the processing of input, depending on the language in which input is provided.

operand2
Passing Parameter Fields:

The FETCH statement may also be used to pass parameter fields to the invoked program. A parameter field may be defined with any format. The parameters are converted to a format suitable for a corresponding INPUT field. All parameters are placed on the top of the Natural stack.

The parameter fields can be read by the FETCHed program using an INPUT statement. The first INPUT statement will result in the insertion of all parameter field values into the fields specified in the INPUT statement. The INPUT statement must have the sign position specification (session parameter SG=ON) for parameter fields defined with numeric format, because each parameter field defined with numeric format in the FETCH statement will receive a sign position if its value is negative.

If more parameters are passed than are read by the next INPUT statement, the extra parameters are ignored. The number of parameters may be obtained with the Natural system variable *DATA.

Note:
If operand2 is a time variable (format T), only the time component of the variable content is passed, but not the date component.

parameter
Date Format:

If operand2 is a date variable, you can specify the session parameter DF (Date Format) as parameter for this variable.

Example

Invoking Program:

** Example 'FETEX1': FETCH  (with parameter)                            
************************************************************************
DEFINE DATA LOCAL                                                       
1 #PNUM (N8)                                                            
1 #FNC  (A1)                                                            
END-DEFINE                                                              
*                                                                       
INPUT 10X 'SELECTION MENU FOR EMPLOYEES SYSTEM' /                       
      10X '-' (35) //                                                   
      10X 'ADD      (A)' /                                              
      10X 'UPDATE   (U)' /                                              
      10X 'DELETE   (D)' /                                              
      10X 'STOP     (.)' //                                             
      10X 'PLEASE ENTER FUNCTION: ' #FNC ///                            
      10X 'PERSONNEL NUMBER:' #PNUM                                     
*                                                                       
DECIDE ON EVERY VALUE OF #FNC                                           
  VALUE 'A', 'U', 'D'                                                   
    IF #PNUM = 0                                                        
      REINPUT 'PLEASE ENTER A VALID NUMBER' MARK *#PNUM
    END-IF                                             
  VALUE 'A'                                            
    FETCH 'FETEXAD' #PNUM                              
  VALUE 'U'                                            
    FETCH 'FETEXUP' #PNUM                              
  VALUE 'D'                                            
    FETCH 'FETEXDE' #PNUM                              
  VALUE '.'                                            
    STOP                                               
  NONE                                                 
    REINPUT 'PLEASE ENTER A VALID FUNCTION' MARK *#FNC 
END-DECIDE                                             
*                                                      
END

Invoked Program FETEXAD:

** Example 'FETEXAD': FETCH (called by FETEX1)                          
************************************************************************
DEFINE DATA LOCAL                                                       
1 #PERS-NR (N8)                                                         
END-DEFINE                                                              
*                                                                       
INPUT #PERS-NR                                                          
*                                                                       
WRITE *PROGRAM 'Record added with personnel number:' #PERS-NR           
*                                                                       
END

Invoked Program FETEXUP:

** Example 'FETEXUP': FETCH (called by FETEX1)                          
************************************************************************
DEFINE DATA LOCAL                                                       
1 #PERS-NR (N8)                                                         
END-DEFINE                                                              
*                                                                       
INPUT #PERS-NR                                                          
*                                                                       
WRITE *PROGRAM 'Record updated with personnel number:' #PERS-NR         
*                                                                       
END

Invoked Program FETEXDE:

** Example 'FETEXDE': FETCH (called by FETEX1)                          
************************************************************************
DEFINE DATA LOCAL                                                       
1 #PERS-NR (N8)                                                         
END-DEFINE                                                              
*                                                                       
INPUT #PERS-NR                                                          
*                                                                       
WRITE *PROGRAM 'Record deleted with personnel number:' #PERS-NR         
*                                                                       
END

Output of Program FETEX1:

SELECTION MENU FOR EMPLOYEES SYSTEM
-----------------------------------
                                   
ADD      (A)                       
UPDATE   (U)                       
DELETE   (D)                       
STOP     (.)                       
                                   
PLEASE ENTER FUNCTION: D            
                                   
                                   
PERSONNEL NUMBER: 1150304

After entering and confirming function and personnel number:

Page      1                                                  05-01-13  11:58:46
                                                                               
FETEXDE  Record deleted with personnel number:   1150304