CALLNAT

M

CALLNAT operand1 [USING] operand2 (AD= O )

A

nX

This document covers the following topics:

CALLNAT Usage
CALLNAT Syntax Description
Parameter Transfer with Dynamic Variables
CALLNAT Examples

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

Belongs to Function Group: Invoking Programs and Routines

CALLNAT Usage

The CALLNAT statement is used to invoke a Natural subprogram for execution. (A Natural subprogram can only be invoked via a CALLNAT statement; it cannot be executed by itself.)

When the CALLNAT statement is executed, the execution of the invoking object (that is, the object containing the CALLNAT statement) will be suspended and the invoked subprogram will be executed. The execution of the subprogram continues until either its END statement is reached or processing of the subprogram is stopped by an ESCAPE ROUTINE statement being executed. In either case, processing of the invoking object will then continue with the statement following the CALLNAT statement.

Notes:

A subprogram can in turn invoke other subprograms.
A subprogram has no access to the global data area used by the invoking object. If a subprogram in turn invokes a subroutine or helproutine, it can establish its own global data area to be shared with the subroutine/helproutine.

CALLNAT 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	C	G	O	yes	yes

Syntax Element Description:

Syntax Element	Description
`operand1`	Subprogram to be Invoked: As `operand1`, you specify the name of the subprogram to be invoked. The name may be specified either as a constant of 1 to 8 characters, or - if different subprograms are to be called dependent on program logic - as an alphanumeric variable of length 1 to 8. The case of the specified name is not translated. The subprogram 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 subprograms for the processing of input, depending on the language in which input is provided.
`operand2`	Parameters: If parameters are passed to the subprogram, the structure of the parameter list must be defined in a `DEFINE DATA PARAMETER` statement. The parameters specified with the `CALLNAT` statement are the only data available to the subprogram from the invoking object. By default, the parameters are passed by reference, that is, the data are transferred via address parameters, the parameter values themselves are not moved. However, it is also possible to pass parameters by value, that is, pass the actual parameter values. To do so, you define these fields in the `DEFINE DATA PARAMETER` statement of the subprogram with the option `BY VALUE` or `BY VALUE RESULT` (see `parameter-data-definition` in the description of the `DEFINE DATA` statement). If parameters are passed by reference, the following applies: The sequence, format and length of the parameters in the invoking object must match exactly the sequence, format and length of the `DEFINE DATA PARAMETER` structure in the invoked subprogram. The names of the variables in the invoking object and the invoked subprogram may be different. If parameters are passed by value, the following applies: The sequence of the parameters in the invoking object must match exactly the sequence in the `DEFINE DATA PARAMETER` structure of the invoked subprogram. Formats and lengths of the variables in the invoking object and the subprogram may be different; however, they have to be data transfer compatible; see the corresponding table in the section Rules for Arithmetic Assignments, Data Transfer in the Programming Guide. The names of the variables in the invoking object and the subprogram may be different. If parameter values that have been modified in the subprogram are to be passed back to the invoking object, you have to define these fields with `BY VALUE RESULT`. When `BY VALUE` is specified without `RESULT`, it is not possible to pass modified parameter values back to the invoking object (regardless of the `AD` specification; see also below). Note: With `BY VALUE`, an internal copy of the parameter values is created. The subprogram accesses this copy and can modify it, but this will not affect the original parameter values in the invoking object. With `BY VALUE RESULT`, an internal copy is likewise created, however, after termination of the subprogram, the original parameter values are overwritten by the (modified) values of the copy. For both ways of passing parameters, the following applies: If a group is specified as `operand2`, the individual fields contained in that group are passed to the subprogram; that is, for each of these fields a corresponding field must be defined in the subprogram's parameter data area. In the parameter data area of the invoked subprogram, a redefinition of groups is only permitted within a `REDEFINE` block. If an array is passed, its number of dimensions and occurrences in the subprogram's parameter data area must be the same as in the `CALLNAT` parameter list. Note: If multiple occurrences of an array that is defined as part of an indexed group are passed with the `CALLNAT` statement, the corresponding fields in the subprogram's parameter data area must not be redefined, as this would lead to the wrong addresses being passed. When the option `PCHECK` of the `COMPOPT` command is set to `ON`, the compiler will check the number, format, length and array index bounds of the parameters that are specified in a `CALLNAT` statement. Also, the `OPTIONAL` feature of the `DEFINE DATA PARAMETER` statement is considered in the parameter check. Note: Numeric constant parameters are internally represented in packed form (format P). For further information see the Programming Guide > Numeric Constants.
`AD=`	Attribute Definition: If `operand2` is a variable, you can mark it in one of the following ways:
	`AD=O`	Non-modifiable, see session parameter `AD=O`. Note: Internally, `AD=O` is processed in the same way as `BY VALUE` (see `parameter-data-definition` in the description of the `DEFINE DATA` statement).
	`AD=M`	Modifiable, see session parameter `AD=M`. This is the default setting.
	`AD=A`	Input only, see session parameter `AD=A`.
	If `operand2` is a constant, `AD` cannot be explicitly specified. For constants `AD=O` always applies.
`nX`	Parameters to be Skipped: With the notation `nX` you can specify that the next `n` parameters are to be skipped (for example, `1X` to skip the next parameter, or `3X` to skip the next three parameters); this means that for the next `n` parameters no values are passed to the subprogram. The possible range of values for `n` is `1 - 4096`. A parameter that is to be skipped must be defined with the keyword `OPTIONAL` in the subprogram's `DEFINE DATA PARAMETER` statement. `OPTIONAL` means that a value can - but need not - be passed from the invoking object to such a parameter.

Parameter Transfer with Dynamic Variables

Dynamic variables may be passed as parameters to a called program object (CALLNAT, PERFORM). A call by reference is possible because the value space of a dynamic variable is contiguous. A call by value causes an assignment with the variable definition of the caller as the source operand and the parameter definition as the destination operand. In addition, a call by value result causes the movement to change to the opposite direction. When using a call-by-reference, both definitions must be DYNAMIC. If only one of them is DYNAMIC, a runtime error is raised. In case of a call by value (result) all combinations are possible.

The following table illustrates the valid combinations of statically and dynamically defined variables of the caller, and statically and dynamically defined parameters concerning the parameter transfer.

Call By Reference

`operand2` of caller	Parameter definition
`operand2` of caller	Static	Dynamic
Static	yes	no
Dynamic	no	yes

The formats of the dynamic variables A or B must match.

Call by Value (Result)

`operand2` of caller	Parameter definition
`operand2` of caller	Static	Dynamic
Static	yes	yes
Dynamic	yes	yes

Note:
When using static/dynamic or dynamic/static definitions, a value truncation may occur according to the data transfer rules of the appropriate assignments.

Example 1

Calling Program:

** Example 'CNTEX1': CALLNAT                                            
************************************************************************
DEFINE DATA LOCAL                                                       
1 #FIELD1 (N6)                                                          
1 #FIELD2 (A20)                                                         
1 #FIELD3 (A10)                                                         
END-DEFINE                                                              
*                                                                       
CALLNAT 'CNTEX1N' #FIELD1 (AD=M) #FIELD2 (AD=O) #FIELD3 'P4 TEXT' 
*                                                                       
WRITE '=' #FIELD1 '=' #FIELD2 '=' #FIELD3                               
*                                                                       
END

Called Subprogram CNTEX1N:

** Example 'CNTEX1N': CALLNAT  (called by CNTEX1)                       
************************************************************************
DEFINE DATA PARAMETER                                                   
1 #FIELDA (N6)                                                          
1 #FIELDB (A20)                                                         
1 #FIELDC (A10)                                                         
1 #FIELDD (A7)                                                          
END-DEFINE                                                              
*                                                                       
*                                                                       
#FIELDA := 4711                                                         
*                                                                       
#FIELDB := 'HALLO'                                                      
*                                                                       
#FIELDC := 'ABC'                                                        
*                                                                       
WRITE '=' #FIELDA '=' #FIELDB '=' #FIELDC '=' #FIELDD                   
*                                                                       
END

Example 2

Calling Program:

** Example 'CNTEX2': CALLNAT                                            
************************************************************************
DEFINE DATA LOCAL                                                       
1 #ARRAY1  (N4/1:10,1:10)                                               
1 #NUM     (N2)                                                         
END-DEFINE                                                              
*                                                                       
*                                                                       
CALLNAT 'CNTEX2N' #ARRAY1 (2:5,*)                                   
*                                                                       
FOR #NUM 1 TO 10                                                        
  WRITE #NUM #ARRAY1(#NUM,1:10)                                         
END-FOR                                                                 
*                                                                       
END

Called Subprogram CNTEX2N:

** Example 'CNTEX2N': CALLNAT  (called by CNTEX2)                       
************************************************************************
DEFINE DATA                                                             
PARAMETER                                                               
1 #ARRAY (N4/1:4,1:10)                                                  
LOCAL                                                                   
1 I      (I2)                                                           
END-DEFINE                                                              
*                                                                       
*                                                                       
FOR I 1 10                                                              
  #ARRAY(1,I) := I                                                      
  #ARRAY(2,I) := 100 + I                                                
  #ARRAY(3,I) := 200 + I                                                
  #ARRAY(4,I) := 300 + I                                                
END-FOR                                                                 
*                                                                       
END