Support and Use of Natural and Non-Natural Objects

#### Search Results

Search

# Support and Use of Natural and Non-Natural Objects

This section covers the following topics:

- Support for Natural Objects from Previous Natural Versions

- Back-End Program Calling Conventions

- LE Subprograms

- External Sort Programs

## Support for Natural Objects from Previous Natural Versions

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

## Back-End Program Calling Conventions

This section describes the conventions that apply to invoking a back-end program.

Notes:

1. Except under z/OS in batch mode, a specified back-end program is not invoked if the Natural session is executing on a Natural Development Server.

This section covers the following topics:

- Back-End Program Calling Conventions (Batch Mode)

- Special Considerations under CICS

- Special Considerations under IMS TM

- Sample Back-End Programs

### Back-End Program Calling Conventions (Batch Mode)

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.

### Special Considerations under CICS

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.

### Special Considerations under IMS TM

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.

### Sample Back-End Programs

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 `XNATBACK` in the Natural source library. This program issues the Natural termination message on both `SYSPRINT` and the operator console; potential termination data is printed on `SYSPRINT` in dump format.

## LE Subprograms

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:

- Support of IBM LE Subprograms

- Enabling Natural Support of LE Subprograms

- Passing LE Runtime Options

- LE Abend Handling

### Support of IBM LE Subprograms

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.

### Enabling Natural Support of LE Subprograms

The following is required to be able to call IBM Language Environment (LE) subprograms from Natural:

1. 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.

2. 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.

3. 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.

4. 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.

### Passing LE Runtime Options

> Under z/OS Batch and TSO:

>   You have three options:

>   1. 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=/,...'

>   2. You can pass LE run-time options by using the `CEEOPTS` input data set in your JCL. With the use of `CEEOPTS` the LE run-time options are also available to all subtasks. The use of `CEEOPTS` is especially required with a Natural RPC server in batch mode.

>      Example:

>          //CEEOPTS  DD   *
>          POSIX(ON)
>          /*

>   3. 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, set `SYSPARM(RMODE24)` as parameter for the assembler rather than changing `NATLEOPT`.

>      If you have other specific requirements for your LE subprograms, you can add the desired LE options for the `CEEXOPT` macro in source module `NATLEOPT`.

> Under IMS TM:

>   You can pass LE run-time options by providing the region-specific run-time options load module `CEEROPT` in your `STEPLIB` concatenation. In addition, the LE library routine retention initialization routine `CEELRRIN` must be present on the `PREINIT` list of your region JCL.

>   The following is a sample definition of a `CEEROPT` load module that allows the execution of `AMODE(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

### LE Abend Handling

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.

## External Sort Programs

This document provides information on using external sort programs with Natural.

The following topics are covered:

- Support of External Sort Programs

- Special Considerations

### Support of External Sort Programs

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`.

### Special Considerations

All external sort programs supporting the extended parameter list can be used.

### On this page

- Support for Natural Objects from Previous Natural Versions
- Back-End Program Calling Conventions
- LE Subprograms
- External Sort Programs