Support and Use of Natural and Non-Natural Objects

This section covers the following topics:

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. This section does not apply to BS2000; refer to Calling Non-Natural Programs and Calling openUTM Chained Partial Programs in the Natural TP Monitor Interfaces documentation, section Natural under openUTM.
  2. 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)

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 NCPRM or 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 (z/OS and z/VSE):

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 (z/OS) or SYSLST (z/VSE) and the operator console; potential termination data is printed on SYSPRINT or SYSLST in dump format.

LE Subprograms

This section applies to z/OS batch mode, z/VSE batch mode, 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

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 subprograms of Natural (LE and non-LE) are loaded via LE services (CEEFETCH or CEELOAD macro). All dynamic subprograms loaded during a Natural session are deleted upon LE environment termination, i.e. during termination of the Natural session. That is, the profile parameter DELETE does not have any effect.

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, the corresponding driver must be generated as described in the appropriate installation steps in Installing Natural CICS Interface on z/OS and Installing Natural CICS Interface on z/VSE 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.

  2. 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 for z/OS or NOAUTO for z/VSE.

  3. 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 z/VSE Batch:

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

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 for z/OS

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

Special Considerations for z/VSE

The external sort program is loaded into the partition program area. For this reason, you must add round about 200 KB additional storage to the size requirements of the Natural batch nucleus specified in the SIZE parameter of the EXEC statement.

Example: 

// EXEC natural,SIZE(natural,200K)

where natural is the name of your Natural phase.

Special Considerations for BS2000

The external sort program is called using the level 1 interface. That is, Natural passes all SORT control statements to the external sort program and data set SYSDTA is not used for input.

The external sort program is searched for in the following libraries:

  • User TASKLIB concatenated with the BLSLIB chain, if a User TASKLIB was specified,

  • System TASKLIB ($TSOS.TASKLIB) concatenated with the BLSLIB chain.