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:

When the job generation is complete, NATRJE transfers the JCL cards to a BS2000 file, which is generated by NATRJE. This is a SAM file that contains the generated JCL cards and is submitted by using the ENTER, ENTER-JOB or ENTER-PROCEDURE command.

Calling NATRJE from a Natural Program

This section covers the following topics:

Invoking NATRJE

Start of instruction set To invoke the NATRJE utility

  • In the Natural program that invokes the NATRJE utility, specify a CALL statement by using the following syntax:

    CALL 'NATRJE' parm1 parm2 parm3 parm4 [parm5]

    Note:
    parm5 only applies to BS2000.

    The parameters specified in the CALL statement are explained in the following table:

    Parameter Explanation
    parm1 The starting JCL card of the table which contains one or more 80-character JCL cards to be submitted.
    parm2 A 4-byte binary field which contains the number of 80-character JCL cards to be submitted.
    parm3
    A 1-byte alphanumeric field used to indicate if all JCL cards have been submitted:
     
    ' ' Not the last call for the current job. A further JCL card follows with the next CALL statement. The JCL cards are collected into the RJE buffer.
     
    B BS2000 and z/OS only: Last call for the current job.

    Under BS2000: The job is generated, written to the file, but not started automatically.

    Under z/OS (batch and TSO, IMS TM and CICS): The job is written to the internal reader data set but not submitted. If function L (see below) is called subsequently, the internal reader is closed and the job(s) are submitted. In addition, the internal reader is closed and the job is submitted either on a screen I/O (IMS TM) or during session termination (z/OS batch, TSO and IMS TM).

     
    C Flush the current job. The job is not submitted to the system. Under BS2000, no file is created.
     
    L Last call for the current job. The job is submitted to the system.
     
    BS2000 environments: see Additional Values for parm3.
    parm4 A 2-byte binary field in which NATRJE returns a response code.
    parm5 Optional parameter for BS2000 only.

    A 1880-byte (maximum) alphanumeric field used to define a list of parameters as highlighted in Example Program 3 for BS2000.

    You can replace the default file names generated by Natural by user-defined names if parm5 starts with a FROM-FILE parameter definition.

    Notes:

    1. Natural only checks the syntax of the FROM-FILE parameter definition in parm5. It is the responsibility of the user to validate the syntax of all other definitions contained in parm5.
    2. parm5 is not evaluated for the ISP ENTER command.

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

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

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

Example Program 3 for BS2000

The following is a Natural example program that submits, in one call to NATRJE, a JCL procedure with two ENTER-PROCEDURE command parameters. 

DEFINE DATA LOCAL
 01 COUNT  (B4)
 01 FLAG   (A1)
 01 RETHEX (B2)
 01 CARDS (A80/1.8) 
 01 01 SDF-COM (A80) INIT <'JOB-NAME=RJEPTEST,RESOURCES=*PAR(RUN-PRIO=230)'> 
END-DEFINE
CARDS (1) := '/BEGIN-PROCEDURE LOGGING=COMMANDS'                       
CARDS (2) := '/ASSIGN-SYSOUT  TO=RJETEST.OUT'                          
CARDS (3) := '/SHOW-JOB-STATUS'                                        
CARDS (4) := '/SHOW-FILE-ATTRIBUTES FILE-NAME=*ALL,SELECT=BY-ATTRIBUTE'
CARDS (5) := '/ASSIGN-SYSOUT  TO=*PRIMARY'
CARDS (6) := '/EXIT-PROCEDURE'            
COUNT := 6                                      /* NUMBER OF CARDS */          
FLAG := 'P'                                     /* LAST CALL OF NATRJE */    
CALL 'NATRJE' CARDS(*) COUNT FLAG RETHEX SDF-COM   
WRITE '=' RETHEX                                   
END

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

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.
9006 File name in FROM-FILE parameter invalid or longer than 54 characters.
D010 Error in ENTER macro.
Dxxx Operating system error:

The error message is sent directly to the user program; the BS2000 HELP command provides additional information.

NATRJE Features Applicable to openUTM/TIAM

This section covers the following topics:

SDF Command SET-LOGON-PARAMETERS

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

  • The only supported command abbreviation for the SET-LOGON-PARAMETERS command is STLGP;

  • If the abbreviation STLGP is used, the value of parm3 must be set to S;

  • The values A and T for parm3 are not supported.

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 operating system, the parameter ERASE=YES is added to the ENTER parameter.
T The job is generated and completed. Before submission to the BS2000 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.
S This value must be set if the abbreviation STLGP for the SDF command SET-LOGON-PARAMETERS is used.
J The SDF command ENTER-JOB is used for job submission.
P The SDF command ENTER-PROCEDURE is used for job submission.

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

Name of BS2000 File

The name of the BS2000 file created by NATRJE for the JCL cards is as follows: 

E.DDMMYY.HHMMSSSS.program-name.user-id - if the ISP command ENTER is used for job submission
J.DDMMYY.HHMMSSSS.program-name.user-id - if the SDF command ENTER-JOB is used for job submission
P.DDMMYY.HHMMSSSS.program-name.user-id - if the SDF command ENTER-PROCEDURE is used for job submission

The parameters are explained in the following table.

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

Optional CALL Parameter for SDF ENTER Commands

Under BS2000, the CALL statement provides the option to submit a JCL procedure along with an ENTER-JOB or ENTER-PROCEDURE command. For details, see the parm5 parameter described in Invoking NATRJE and Additional Values for parm3.

For an example of a program call, see Example Program 3 for BS2000.