Version 4.2.6 for Mainframes
 —  Utilities  —

NATRJE Utility - Natural Remote Job Entry

The NATRJE utility (Natural Remote Job Entry) can be used to submit JCL cards from a Natural program to the operating system for scheduling and execution. For example, it is possible to start a Natural batch job with NATRJE.

The NATRJE Utility - Natural Remote Job Entry documentation covers the following topics:

Related Topic:


General Information on NATRJE

The following graphic is a simplified functional diagram of the NATRJE utility:

Legend

The Natural program calls the NATRJE utility for the purpose of submitting JCL cards to be executed by the operating system.

NATRJE collects the JCL cards into the RJE buffer until the Natural program indicates that the job is complete. The RJE buffer holds the JCL cards before they are submitted. The initial size of the RJE buffer is determined by the RJESIZE profile parameter (as described in the Parameter Reference documentation). If a given job does not fit into the RJE buffer, the buffer is automatically enlarged. The maximum size of a job is determined by the thread or region size.

NATRJE transfers the JCL cards to the operating system internal job queue for scheduling and execution by the operating system.

Note for BS2000/OSD:
When the job generation is complete, NATRJE transfers the JCL cards to a BS2000/OSD dataset, which is generated by NATRJE. The dataset is a SAM file that contains the generated JCL cards and is submitted by using the ENTER command.

Top of page

Calling NATRJE from a Natural Program

This section covers the following topics:

Invoking NATRJE

Start of instruction set To invoke the NATRJE utility

Example Programs

This section provides Natural example programs that submit JCL cards:

Example Program for z/OS

The following is a Natural example program that submits, in one call to NATRJE, a three-card JCL stream.

DEFINE DATA LOCAL
   01 COUNT  (B4)
   01 FLAG   (A1)
   01 RETHEX (B2
   01 CARDS  (A240
   01 REDEFINE CARDS
      02 CARD1 (A80)
      02 CARD2 (A80)
      02 CARD3 (A80)
  END-DEFINE
  MOVE '//JOBN JOB CLASS=G,MSGCLASS=X' TO CARD1
  MOVE '//XXX EXEC PGM=IEFBR14' TO CARD2
  MOVE '//DD1 DD DSN=NATRJE.SOURCE,DISP=SHR' TO CARD3
  MOVE 3 TO COUNT
  MOVE 'L' TO FLAG
  CALL 'NATRJE' CARDS COUNT FLAG RETHEX
  IF RETHEX = H'0000'
    WRITE 'JOB submitted successfully'
  ELSE
    WRITE 'ERROR from NATRJE' RETHEX
  END-IF
  END

Example Program for z/VSE

The following is a Natural example program that submits, in three calls to NATRJE, a seven-card JCL stream.

DEFINE DATA LOCAL
   01 COUNT  (B4)
   01 FLAG   (A1)
   01 RETHEX (B2)
   01 CARDS  (A240)
   01 REDEFINE CARDS
      02 CARD1 (A80)
      02 CARD2 (A80)
      02 CARD3 (A80)
  END-DEFINE
  MOVE '* $$ JOB JNM=DSERV,CLASS=0,DISP=D' TO CARD1
  MOVE '* $$ LST CLASS=A,DISP=D' TO CARD2
  MOVE '// JOB DSERV TO DSERV SOURCE MEMBERS' TO CARD3
  MOVE 3 TO COUNT
  CALL 'NATRJE' CARDS COUNT FLAG RETHEX
  PERFORM RETCODE-CHECK
  MOVE '// EXEC PROC=NATSPLP' TO CARD1 
  MOVE '// EXEC  DSERV' TO CARD2
  MOVE ' DSPLYS SD' TO CARD3
  MOVE 3 TO COUNT
  CALL 'NATRJE' CARDS COUNT FLAG RETHEX
  PERFORM RETCODE-CHECK
  MOVE '/*' TO CARD1
  MOVE '/&' TO CARD2
  MOVE '* $$ EOJ' TO CARD3
  MOVE 3 TO COUNT
  MOVE 'L' TO FLAG
  CALL 'NATRJE' CARDS COUNT FLAG RETHEX
  DEFINE SUBROUTINE RETCODE-CHECK
  IF RETHEX NE H'0000'
    WRITE 'ERROR from NATRJE:' RETHEX
  STOP
  END-IF
  END-SUBROUTINE
  END

Example Program 1 for BS2000/OSD

The following is a Natural example program that submits, in three calls to NATRJE, a nine-card JCL stream.

DEFINE DATA LOCAL
   01 COUNT  (B4)
   01 FLAG   (A1)
   01 RETHEX (B2)
   01 CARDS  (A240)
   01 REDEFINE CARDS 
      02 CARD1 (A80)
      02 CARD2 (A80)
      02 CARD3 (A80)
  END-DEFINE 
  MOVE '/LOGON' TO CARD1
  MOVE '/SYSFILE SYSDTA=(SYSCMD)' TO CARD2 
  MOVE '/SYSFILE SYSIPT =IPT.PARM' TO CARD 3
  MOVE 3 TO COUNT 
   CALL 'NATRJE' CARDS COUNT FLAG RETHEX 
    IF RETHEX NE H'0000' DO
     WRITE RETHEX (EM=HH)
   END-IF
  MOVE '/SETSW ON=2' TO CARD1 
  MOVE '/EXEC NATBATCH' TO CARD2
  MOVE 'LOGON APPLIC' TO CARD3
  MOVE 3 TO COUNT
  CALL 'NATRJE' CARDS COUNT FLAG RETHEX 
   IF RETHEX NE H'000' DO
   ...
   ...
   END-IF 
  MOVE 'RUNPGM' TO CARD1 
  MOVE 'FIN' TO CARD2 
  MOVE '/LOGOFF' TO CARD3 
  MOVE 3 TO COUNT 
  MOVE 'L' TO FLAG 
  CALL 'NATRJE' CARDS COUNT FLAG RETHEX 
   ...
   ... 
   ...
  END

Example Program 2 for BS2000/OSD

The following is a Natural example program that submits, in one call to NATRJE, a nine-card JCL stream.

DEFINE DATA LOCAL
   01 COUNT  (B4)
   01 FLAG   (A1)
   01 RETHEX (B2)
   01 CARD1 (A80) 
   01 CARD2 (A80) 
   01 CARD3 (A80)
   01 CARD4 (A80)
  ...
   01 CARD9 (A80)
  END-DEFINE
  MOVE '/LOGON' TO CARD1  
  MOVE '/SYSFILE SYSDTA=(SYSCMD)' TO CARD2
  ...
  MOVE '/LOGOFF' TO CARD9  
  MOVE 9 TO COUNT 
  MOVE 'L' TO FLAG
   CALL 'NATRJE' CARD1 COUNT FLAG RETHEX 
  ... 
  END

Top of page

NATRJE Return Codes

A Natural program that issues a CALL statement to NATRJE results in one of the following return codes being returned in the fourth parameter of the statement. There are return codes that apply to all environments and additional codes that are dependent on the operating system:

Return Codes Common to all Environments

Return Code/Hexadecimal Return Code/Decimal Explanation
00 00 Normal return.
04 04 NATRJE utility not available.
08 08 NATRJE utility disabled; a possible reason is that the RJESIZE profile parameter is set to 0 (see also the Parameter Reference documentation).
0C 12 Invalid number of JCL cards.
10 16 Invalid function code.
14 20 No RJE buffer space available.
18 24 Invalid number of parameters.
1C 28 I/O error during submit.
20 32 Job flushed by user exit NREXPG (see NREXPG - User Exit for NATRJE in the Operations documentation).

Additional Return Codes for CICS and Batch under z/VSE

Return Code Explanation
ffrr ff is the XPCC request function code and rr the associated return code.

Additional Return Codes for CICS under z/OS

Return Code Explanation
01nn CICS WRITEQ TD failure; nn is the CICS response code in hexadecimal format.
01nn CICS CLOSE TD failure; nn is the CICS response code in hexadecimal format.

Additional Return Codes under BS2000/OSD

Return Code Explanation
9001 No RJE buffer found.
9002 No buffer space available.
9003 Missing LOGON command.
9004 Only LOGON cards generated.
9005 Too many LOGON parameters.
D010 Error in ENTER macro.
Dxxx Operating system error:
The error message is sent directly to the user program; the BS2000/OSD HELP command provides additional information.

Top of page

NATRJE Features Applicable to openUTM/TIAM

This section covers the following topics:

SDF Command SET-LOGON-PARAMETER

You can replace the ISP command LOGON by the SDF command SET-LOGON-PARAMETER in the first JCL card of the job to be executed. However, the following restrictions apply when using the SDF command:

Examples of ISP and SDF Commands:

ISP command

/.job-id LOGON user-id,account-number,’password

and corresponding SDF command:

/.job-id STGLP user-id,account-number,’password

SDF command with additional keyword operands:

/.job-id STGLP user-id,account-number,’password’, -
/RESOURCES=*PARAMETERS(RUN-PRIORITY=220)

Additional Values for parm3

Value Explanation
A Combination of values T and E (see below).
E The job is generated and completed. Before submission to the BS2000/OSD operating system, the parameter ERASE=YES is added to the ENTER parameter.
T The job is generated and completed. Before submission to the BS2000/OSD operating system, a time limit is calculated using the Natural MT parameter (see also the Parameter Reference documentation). If MT is set to 0, the time limit is generated as NTL. The calculated time limit is added to the ENTER parameter via the TIME=operand.

When using the values T, E or A, NATRJE does not check whether the parameters TIME= or ERASE= exist in the user-created LOGON cards.

Name of BS2000/OSD Dataset

The name of the BS2000/OSD dataset created by NATRJE for the JCL cards is as follows:

E.DDMMYY.HHMMSSSS.program-name.user-id
Parameter Explanation
DD The day of the dataset creation.
MM The month of the dataset creation.
YY The year of the dataset creation.
HH The hour of the dataset creation.
MM The minute of the dataset creation.
SSSS The seconds and milliseconds of the dataset creation.
program-name The name of the Natural program that creates the dataset.
user-id The corresponding Natural user ID.

Top of page