Natural 3GL CALLNAT Interface - Usage, Examples

This section describes the usage of the 3GL CALLNAT interface and describes a number of sample 3GL CALLNAT environments.

The section covers the following topics:

Usage

The following topics are covered:

Overview

When you invoke a Natural subprogram from a 3GL program, a Natural session must be active, i.e. the 3GL program itself must be called by Natural.

Therefore you must take special precautions if you do not want the Natural layer to show up. The following figure is intended to give you an overview of how an application using the Natural 3GL CALLNAT interface may be designed in such a case:

The necessary environment is established by first invoking a Natural start-up program. By using the Natural CALL statement, this start-up program can then invoke a 3GL program from where you can invoke the CALLNAT interface.

Call Structure

The Natural main program is very simple; it only calls, for example, a COBOL program: 

.....
CALL 'COBPGM'
END
.....

The CALL statement of the 3GL programming language (for example, COBOL) must have access to the Natural 3GL CALLNAT interface, which then invokes the Natural subprogram: 

.....
CALL 'interface' USING natpgm p1 ... pn
.....

The parameter interface is environment-dependent (for example, NATXCAL) and linked to the calling program. The parameter natpgm must be an alphanumeric variable of 8 bytes that contains the name of the Natural subprogram to be invoked. The parameters p1 ... pn are passed to the Natural subprogram.

Example (for all environments except CICS):

The COBOL program COBPGM could contain coding similar to the following one: 

.....
MOVE 'FINDNPGM' TO natpgm
CALL 'interface' USING natpgm number name
IF natpgm NE 'FINDNPGM'
THEN GOTO error_handling_1
.....

The invoked Natural subprogram FINDNPGM calculates the number of persons in the file EMPLOYEES with name equal to a value passed from the COBOL program: 

DEFINE DATA
PARAMETER
1 pnumber (P10)
1 pname (A20)
LOCAL
1 emp VIEW OF employees
END-DEFINE
*
RESET presp
FIND NUMBER emp WITH name=pname
MOVE *NUMBER TO pnumber
ESCAPE ROUTINE

If an error occurs while the subprogram is executed, information about this error will be returned in the variable natpgm in the form *NATnnnn, where nnnn is the corresponding Natural error number.

Example (for CICS only):

Under CICS, the call of a Natural subroutine from, for example, COBOL should be as follows: 

...
WORKING STORAGE SECTION
...
01 PARM-LIST PIC X(132).
01 NATPGM PIC X(8).
01 NUMBER PIC 9(10) comp-3.
01 NAME PIC X(20).
...
PROCEDURE DIVISION
...
MOVE 'FINDNPGM' TO NATPGM
CALL 'NCIXCPRM' USING PARM-LIST NATPGM NUMBER NAME ...
EXEC CICS LINK PROGRAM('NCIXCALL')
COMMAREA(PARM-LIST) LENGTH(132) END-EXEC.
...

The called subroutine NCIXCPRM builds the parameter address list used as COMMAREA in the subsequent EXEC CICS LINK command.

Parameter Handling

There is no format and length checking. It is the caller's responsibility to pass a correct parameter list. The number, format and length of the parameters are defined by the invoked Natural subprogram.

When you are passing parameters, group arrays should not be passed, since they are resolved as individual arrays:

Example of Invalid Syntax:

..... 
01 GROUP (1:2)          
02 F1
02 F2
.....
..... 
CALL ..... F1 F2 
.....

Example of Valid Syntax:

.....
01 F1 (1:2)
01 F2 (1:2)
....
.....
CALL ..... F1 F2
.....

Arrays with dynamic ranges cannot be used as parameters.

Sample Environments

The objective for the sample 3GL CALLNAT environments below is to demonstrate how a COBOL routine can call a Natural subprogram under specific TP-monitor systems or in batch mode, and to give system-specific instructions to create such environments.

The following topics are covered:

Sample Environment for CICS

Perform the following steps to create a sample Natural 3GL CALLNAT environment under CICS:

Step 1: Create the Environment Initialization

  • Set up the front-end program that initializes the 3GL CALLNAT environment.

  • Use the COBOL front-end XNCIFRCX in the Natural/CICS source library. It starts Natural, stacks LOGON YOURLIB and executes the program TSTCOB, which initializes the Natural 3GL CALLNAT environment.

  • Locate the string NCvr (where vr represents the relevant product version) in the source code and replace it with the valid transaction ID for Natural.

  • Compile and link-edit the COBOL program and define program to CICS via CEDA DEFINE PROGRAM.

Step 2: Install the Sample COBOL Call

Provided in the Natural/CICS source library NCI.SRCE is the sample member XNCI3GC1, which contains a default call to the Natural subprogram MYPROG.

  • For test purposes, create the following program in the library SYSTEM and stow it as: 

    WRITE 'BEFORE PGM EXECUTION'
CALL 'COBNAT'
WRITE 'AFTER PGM EXECUTION'
END

  • Look at the XNCI3GC1 source and review the CALL and LINK. Compile and link as COBNAT with the following CICS INCLUDE directives or use Step 2 of the Sample Job NCTI070: 

    INCLUDE CICSLIB(DFHECI)
INCLUDE XNCI3GC1                    <= output from translator and compiler
INCLUDE NCILIB(NCIXCPRM)
ENTRY XNCI3GC1
NAME COBNAT(R)
Step 3: Create a Sample Natural Subprogram

By default, the source member XNCI3GC1 is set up to call the Natural subprogram MYPROG in the library YOURLIB. The program TSTCOB, as mentioned above, starts up the process by calling COBNAT that contains the actual call to the Natural subprogram MYPROG.

  • Create the subprogram MYPROG to demonstrate the executing Natural subprogram. 

    DEFINE DATA PARAMETER
  01 PARM1 (A18)
  01 PARM2 (A18)
  01 PARM3 (A18)
END-DEFINE
*
  MOVE 'PARAM01' TO PARM1
  MOVE 'PARAM02' TO PARM2
  MOVE 'PARAM03' TO PARM3
END
Step 4: Verify the CICS Resources

  • Use the job NCII005 for a guide to defining the CICS resources (PPT and PCT).

  • Define the required CICS resources (PPT and PCT).

Step 5: Test the Environment

Test the environment by using the NCYC default transaction. Use CEDF to monitor the program control and observe the data areas in use.

Important:
Since Natural is at the top of the CICS program hierarchy, any COBOL subprogram issuing terminal I/Os must run in conversational mode. Pseudo-conversational programs would need to be modified, and any new development using the Natural 3GL CALLNAT interface should be done in conversational mode.

More Samples

Sample Program Description
XNCI3GC2 COBOL sample with same functionality as XNCI3GC1, but accepting parameters from the calling Natural program.
XNCI3GP1 PL/I sample with same functionality as COBOL sample XNCI3GC1.
XNCI3GP2 PL/I sample with same functionality as XNCI3GC1, but accepting parameters from the calling Natural program.

More Non-CICS Samples

Sample Program Description
XNAT3GC2 COBOL sample with same functionality as CICS sample XNCI3GC2.
XNAT3GP2 PL/I sample with same functionality as CICS sample XNCI3GP2.

Sample for Any Other Supported Environment

Perform the following steps to create a sample Natural 3GL CALLNAT:

Step 1: Assemble and Link ASMNAT

The sample Assembler routine XNAT3GA1 contains a basic example to access the CALLNAT interface. The register calling conventions are in the source of this program.

Link NATXCAL with XNAT3GA1 with entry point ASMNAT.

Step 2: Start the Natural Session

Start a Natural session stacking a program that calls the ASMNAT program which in turn calls the Natural subroutine ASMNAT.