Version 4.2.6 for Mainframes
 —  Operations  —

Back-End Program Calling Conventions

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

Notes:

The following topics are covered:


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:

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.

Top of page

Special Considerations under CICS

Under CICS, the back-end program parameter data are 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 parameter COMAMSG=NO is set in the Natural/CICS generation macro (NCIPARM), only the termination data are passed in the COMMAREA.

Top of page

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.

Top of page

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

Top of page