This section covers the following topics:
Natural objects created in an earlier version of Natural can be executed in the current Natural version without any adjustments to the objects or any conversion or migration procedure being required. This also applies to objects that have been cataloged with the Natural Optimizer Compiler.
For details about supported Natural versions, see Software AG Product Versions Supported by Natural in the current Natural Release Notes for Mainframes
This section describes the conventions that apply to invoking a back-end program.
Notes:
This section covers the following topics:
If the profile parameter PROGRAM
is
specified (or set dynamically during a Natural session by calling the
subprogram CMPGMSET
in the library SYSEXTP
), a
back-end program is invoked, regardless of whether the session terminated
normally or abnormally. The back-end program is called using standard OS
linkage conventions and must return the control to its caller.
If a back-end program is available, Natural does not issue any
session termination messages. Non-zero user return codes, specified via
operand1
of the Natural
TERMINATE
statement,
are indicated by the Natural error message NAT9987.
A parameter area containing the following information is passed to the back-end program:
a fullword that holds the Natural system or user return code,
a Natural termination message of 72 characters,
a fullword that holds the length of the Natural termination data (or zero),
the termination data passed by
operand2
of the
TERMINATE
statement
(if any).
The back-end program parameter area is at least 80 bytes long. The
macro NAMBCKP
, which contains a DSECT
layout of the
back-end program parameter area, is supplied in the Natural source library and
can be used by Assembler back-end programs.
Under CICS, the back-end program parameter data is passed in the
COMMAREA and in the TWA. In the TWA, only 80 bytes are passed, containing
return code and message, while the length field contains an address that points
to the full back-end program parameter area. The same TWA is also provided if
Natural has been invoked via EXEC CICS LINK
; see also
Natural under CICS,
Front-End
Invoked via LINK in the Natural TP Monitor
Interfaces documentation.
If the parameter BACKRPL=ALL
is set in the
NTCICSP
macro (depending on the Natural CICS Interface version installed), only the
termination data is passed in the COMMAREA.
Under IMS TM, the calling conventions for a back-end program are different in a dialog-oriented environment. There, the back-end program is called by a program-to-program switch and the name of the back-end program is used as an IMS TM transaction code. In this case, the Natural environment is terminated before the program-to-program switch takes place; see Natural under IMS TM, Support of Natural Profile Parameter PROGRAM in the Natural TP Monitor Interfaces documentation.
The following table contains a number of sample programs:
Sample Back-end Program for Batch and TSO
Environments in COBOL:
LINKAGE SECTION 01 BACKEND-PARM-AREA. 02 TERMINATION-RETURN-CODE PIC S9(8) COMP. 02 TERMINATION-MESSAGE PIC X(72). 02 TERMINATION-DATA-LENGTH PIC S9(8) COMP. 02 TERMINATION-DATA PIC X(100) ... PROCEDURE DIVISION USING BACKEND-PARM-AREA |
Sample Back-end Program for Batch and TSO
Environments in Assembler:
BACKPROG CSECT SAVE (14,12) LR 11,15 USING BACKPROG,11 L 2,0(1) USING BCKPARM,2 ... RETURN (14,12) BCKPARM NAMBCKP END |
Sample Back-end Program for CICS in
Assembler:
L 2,DFHEICAP USING BCKPARM,2 ... BCKPARM NAMBCKP END |
Sample Back-end Program XNATBACK for Batch
Mode:
A sample program for batch mode is supplied as
|
This section applies to z/OS batch mode, CICS, Com-plete, IMS TM and TSO. It provides information on how Natural supports IBM Language Environment (LE) subprograms.
This section covers the following topics:
To support IBM Language Environment (LE) subprograms, Natural must
be prepared for the CALL
statement to be able to call LE subprograms. LE subprograms can be static
(profile parameters CSTATIC
and
RCA
) or
dynamic subprograms of Natural.
Dynamic LE subprograms of Natural are loaded via the
CEEFETCH
LE service and deleted by the CEERELES
service as per the DELETE
profile
parameter.
The following is required to be able to call IBM Language Environment (LE) subprograms from Natural:
When installing Natural CICS Interface, the environment-dependent nucleus must be generated as described in the appropriate installation steps in Installing Natural CICS Interface on z/OS in the Installation documentation.
For LE enablement of Natural under CICS, see also the appropriate installation steps and the section Natural CICS Interface and IBM Language Environment (LE) in the TP Monitor Interfaces documentation.
For LE enablement of Natural under Com-plete, the LE370
keyword
subparameter of the NTCOMP
macro must be set to ON
(see
the Parameter Reference documentation). See also the chapter
IBM Language Environment Considerations in your
Com-plete documentation.
The IBM LE runtime modules must automatically be included from the IBM LE library during the linkage editor step. There must not be any unresolved externals starting with "CEE". Do not set the linkage editor option NCAL.
Under z/OS batch, IMS TM and TSO, Natural can also call LE
main programs, but only as dynamic subprograms. If an LE main program is to be
called dynamically, this has to be indicated by specifying
SET CONTROL
'P=L'
before the CALL
statement. Otherwise, the LE
environment created by Natural will be terminated by the LE main program.
- Under z/OS Batch and TSO:
You have three options:
You can pass LE run-time options by using the
PARM=
parameter in your JCL. The following applies:
The run-time options that are passed to the main routine must be followed by a slash (/) to separate them from the Natural parameters.
If you want to use a slash within your Natural parameters, then your Natural parameters must begin with a slash.
Example:
PARM='/ID=/,...'You can pass LE run-time options by using the
CEEOPTS
input data set in your JCL. With the use ofCEEOPTS
the LE run-time options are also available to all subtasks. The use ofCEEOPTS
is especially required with a Natural RPC server in batch mode.Example:
//CEEOPTS DD * POSIX(ON) /*You can define LE run-time options by modifying and re-assembling the supplied source module
NATLEOPT
. For example, if you have any subprograms still running in 24 bit mode, setSYSPARM(RMODE24)
as parameter for the assembler rather than changingNATLEOPT
.If you have other specific requirements for your LE subprograms, you can add the desired LE options for the
CEEXOPT
macro in source moduleNATLEOPT
.- Under IMS TM:
You can pass LE run-time options by providing the region-specific run-time options load module
CEEROPT
in yourSTEPLIB
concatenation. In addition, the LE library routine retention initialization routineCEELRRIN
must be present on thePREINIT
list of your region JCL.The following is a sample definition of a
CEEROPT
load module that allows the execution ofAMODE(24)
subprograms:CEEROPT CSECT CEEROPT AMODE ANY CEEROPT RMODE ANY CEEXOPT ALL31=((OFF),OVR), X STACK=((128K,128K,BELOW,KEEP,512K,128K),OVR) END CEEROPT
Natural supports the LE-specific user error handling, that is, if
an LE subprogram has defined a user error handler, this handler gets control
when an abend, a program check or any other LE error condition occurs in the
subprogram. If no LE user error handler has been defined, Natural reacts
according to the setting of the DU
profile
parameter.
In this case, a special error message (NAT0950 if
DU=OFF
or NAT9967 if DU=ON
) is issued which indicates
the LE error number. In addition, the corresponding LE error message is issued
on CEEMSG
and an LE snap dump is written to CEEDUMP
according to LE run-time option TERMTHDACT
.
Note:
In case of DU=FORCE
, the abend handling of Natural
is disabled and the LE error handling takes place even if no LE subprogram is
active at the time of the abend. In this case, it is strongly recommended to
specify the LE run-time option TERMTHDACT(UAIMM)
to get all
required diagnostic information.
This document provides information on using external sort programs with Natural.
The following topics are covered:
The Natural SORT
statement may optionally
invoke an external sort program that carries out the actual sorting. An
external sort program is used if the keyword subparameter
EXT
of the
macro NTSORT
is set to ON
in the
Natural
parameter module.
Natural supports all external sort programs that comply with the sort interface documented in the manuals for the relevant operating system.
The requirements (for example, space and data sets) are identical to those for the execution of a 3GL (for example, COBOL, PL/I) application program that invokes the operating system sort program and can vary according to the external sort program in use.
The communication with the external sort program is via the E15
and E35 user-exit routines. As a consequence, Natural does not require the data
sets SORTIN
and SORTOUT
.
All external sort programs supporting the extended parameter list can be used.