This document describes the conventions that apply to invoking a back-end program.
Notes:
This section does not apply to BS2000/OSD; refer to Calling Non-Natural Programs and Calling UTM Chained Partial Programs in the Natural TP Monitor Interfaces documentation, section Natural under UTM.
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.
The following topics are covered:
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 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.
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 (z/OS
and z/VSE):
A sample program for batch mode is supplied as
|