This document describes the purpose of the 3GL CALLNAT interface and its prerequisites and restrictions.
The section covers the following topics:
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.
The interface is available in batch mode under z/OS and for the following TP-monitor environments:
CICS,
Com-plete,
IMS TM,
TSO.
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.
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.
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.
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:
|
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.
|
The invoked Natural subprogram should be terminated with a return to the calling program.
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).
The parameter values passed by the 3GL program must not reside in a write-protected storage area.
Arrays with dynamic ranges are not possible.
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).