Natural 3GL CALLNAT Interface - Purpose, Prerequisites, Restrictions

#### Search Results

Search

# Natural 3GL CALLNAT Interface - Purpose, Prerequisites, Restrictions

This document describes the purpose of the 3GL CALLNAT interface and its prerequisites and restrictions.

The section covers the following topics:

- Purpose of 3GL CALLNAT Interface

- Prerequisites

- Restrictions

## Purpose of 3GL CALLNAT Interface

With the 3GL CALLNAT interface, Natural enables 3GL programs to invoke and execute Natural subprograms.

The 3GL can be any programming language which supports the standard linkage call interface. In most cases this will be a COBOL program, but the functionality can also be used by, for example, PL/1, FORTRAN, C or Assembler programs.

### Availability

The interface is available in batch mode under z/OS and for the following TP-monitor environments:

- CICS,

- Com-plete,

- IMS TM,

- TSO.

## Prerequisites

This section describes the prerequisites to execute a Natural subprogram from a 3GL program, using an internal `CALLNAT` statement. To achieve the desired functionality, a Natural environment must be set up before you execute the `CALLNAT` interface from your 3GL program.

- Space Requirements

- Linking

- Environment Dependencies

### Space Requirements

The mechanism of parameter addressing in a Natural program requires that the parameters passed reside in an area allocated by Natural, that is, in any of its sizes. The 3GL program, however, allocates the storage for its variables somewhere in the address space of the task. To make addressing still successful, a "call-by-value" mechanism is used for those variables which do not already reside in a Natural area. This means that, prior to invoking the Natural subprogram, the parameters to be passed are transferred into a Natural area, namely the `DATSIZE` buffer.

In addition to the storage used for the contents of the variables, additional storage will be needed depending on the number of parameters. The total amount of space required is approximately the same as the space that would be needed in the `DATSIZE` buffer if the subprogram-invoking program were coded in Natural.

### Linking

To invoke the Natural subprogram, the 3GL program must call the `CALLNAT` interface. Depending on the power and functionality of the call interface of the 3GL programming language, the `CALLNAT` interface can be either placed in an accessible load library for dynamic loading or linked to the 3GL program.

It is recommended, whenever possible, to load the `CALLNAT` interface dynamically from a Natural steplib, as this method makes sure that always the most recent version of that program is used.

The samples `XNATGC2` and `XNATGCP2` are provided to elucidate the technique of dynamically loading and calling the `CALLNAT` interface from COBOL or PL/I, respectively.

Note
Check with the responsible system programmer for the best solution in your environment.

### Environment Dependencies

The foreign 3GL module can be either linked to Natural as a `CSTATIC` module and then invoked via a branch and link instruction, or loaded dynamically and invoked via a TP-dependent link method.

In the latter case, the 3GL module is written in a TP-specific way and the `CALLNAT` interface must be adapted accordingly. For this purpose, multiple TP-specific interface modules are provided:

Interface Module | Purpose
--- | ---
`NATXCAL` | To be used in the following cases: if the 3GL module is either loaded dynamically or linked to Natural and then invoked by a branch and link instruction (batch, Com-plete, IMS TM, TSO, `%P=S` and `%P=LS` in CICS). if the 3GL module is called via the `INTERFACE4` option of the `CALL` statement. It provides the `INTERFACE4` Natural Callnat Interface as well as the `INTERFACE4` Callback Functions. For further information on the `INTERFACE4` functionality, see the `CALL` statement documentation. Note For `CALL INTERFACE4` purposes, `NATXCAL` cannot be loaded dynamically but must be linked to the 3GL program.
`NCIXCALL` | To be used in a CICS environment if the 3GL module has been invoked using `EXEC CICS LINK`; `NCIXCALL` is delivered in source code to be compiled with your CICS macros. See also Installing the Natural CICS Interface on z/OS in the Installation documentation.
`NCIXCPRM` | To be used in a CICS environment to build the parameter address list used as `COMMAREA` for the subsequent `EXEC CICS LINK` command.

## Restrictions

### Terminating a Natural Subprogram

The invoked Natural subprogram should be terminated with a return to the calling program.

### Inadmissible Natural Statements

The following statements must not be used.

- `FETCH`

- `RUN`

- `STOP`

- `TERMINATE`

When used in the invoked Natural subprogram they will bring about an appropriate Natural runtime error (NAT0967).

### Parameter Values Passed by the 3GL Program

The parameter values passed by the 3GL program must not reside in a write-protected storage area.

### Dynamic Arrays

Arrays with dynamic ranges are not possible.

### TP-Monitor-Specific Restrictions

- Under CICS
  For CICS environments, the 3GL program that uses the Natural 3GL CALLNAT interface must be written for conversational mode. The 3GL program runs on the second CICS program level and pseudo-conversational program technique can therefore not be used.

- Under IMS TM
  IMS TM environments running Natural can use the 3GL CALLNAT interface only if both the 3GL program and the Natural subprogram do not issue any terminal I/O; when `DISPLAY`, `INPUT` and `WRITE` are used in the invoked Natural subprogram they will bring about an appropriate Natural runtime error (NAT0967).

### On this page

- Purpose of 3GL CALLNAT Interface
- Prerequisites
- Restrictions