Editing Master JCL and Natural Sources

JCL and Natural source objects can be edited with the internal editor.

By editing the master JCL, you change the master definition that affects each future executed active job.

This document covers the following topics:

Related Topics:

General Editing Considerations

Automatic Logon to the Operating System Server

Before JCL is edited, Entire Operations checks whether the user may access the JCL file. If it is an operating system file, then an automatic logon with the defined JCL user ID (BS2000 and UNIX and Windows) will be carried out, if required. If this automatic logon does not function (e.g., if a password is required), then this will be displayed to the user. In this case, he must first logon to the corresponding operating system server.

Logon to a Node

While editing the master JCL, an implicit logon is triggered to establish the connection to the required node. The logon is not prompted if you have already logged on to this node within this session.

For further information, see the logon function described in the section Using Entire Operations GUI Client.

Windows: File Names

File names in Windows can be written in an alternative notation if the backslash character (\) is not available, like in mainframe environments. See File Names in Job Control for Jobs under Windows in the section System Overview.

UNIX and Windows: Text Files

If a file to be edited or loaded as JCL is not a text file, the error message EOR0325 - No Text File is returned. For JCL loading, this is treated as a permanent error.

UNIX and Windows: Handling of Tab Characters (H'09') within JCL Lines

  • If a master or active JCL is edited, each tab character is converted to a single blank before the editing. This prevents strange effects during editing. The JCL is written back without tab characters in any case.

  • Extended logging, JCL logging: for the extended logging of JCL tab characters are also converted to blanks.

  • If Entire Operations is running on a mainframe, the middleware translation tables convert tab characters to blanks anyway. This means that each UNIX and Windows JCL is being submitted without tab characters.

  • If Entire Operations is running on UNIX or Windows, tab characters remain in master and active JCL, as long as the master or active JCL is not edited from within Entire Operations.

Usage of Text Objects in JCL

Entire Operations allows the inclusion of text objects into JCL. The text objects can have their own local parameters. Text objects can invoke other text objects, i.e., nesting is possible.

Text object inclusion can be used not only for macro jobs with JCL location MAC (macro Natural source), but also for other JCL locations.

For information about including a text object, see Inserting Text Objects into JCL.

Using the Editor

This section describes how to edit JCL and Natural sources including user exits.

Start of instruction set To edit JCL of a standard operating system job or a Natural source

  1. In the object workspace, select a Job Master instance and choose Edit Master JCL or Edit Active JCL from the context menu.

    Or:
    On the JCL Definition page in the Maintenance Job Master or Maintenance Job Active window, choose Edit (see also Functions: Master JCL Definition).

    An Edit window similar to the following examples opens.

    (If the source of the specified JCL member does not yet exist, the Edit window is empty.)

  2. Edit the source as required.

    You can use the editor functions provided in the context menu of the Edit window (or the toolbar of the main application window) to find and change text, navigate in the source or perform special functions for macro sources. See Available Functions: Edit Window and Editing Macro Sources for Dynamic JCL Generation.

Start of instruction set To edit the source of a user exit

  1. In the object workspace, select a Job Master instance and open the Input Conditions page.

    Select an input condition of the type Exit.

    Choose Edit.

    Or:
    In the object workspace, select a Job Master instance and open the EOJ Checking page.

    Select an action user exit (indicated by an X in the Action column) or a checking user exit and choose Edit Action Exit or Edit User Exit, respectively.

    An Edit window similar to the following opens:

    graphics/edit_user_exit.png

    (If the source of the selected user exit has not yet been created and cataloged, the Edit window only contains an incomplete DEFINE sample statement.)

  2. Edit the source as required.

    In order to use a user exit, it must be saved and cataloged as a Natural object in a Natural library.

    For information on coding action user exits, see also User Exits for End-of-Job Checking and Actions in the section User Exits.

    You can use the editor functions provided in the context menu of the Edit window (or the toolbar of the main application window) to find and change text, navigate in the source or perform special functions for macro sources. See Available Functions: Edit Window.

This section covers the following topics:

Available Functions: Edit Window

The following functions are provided from the context menu in an Edit window or the toolbar in the main application window:

Function Shortcut Description
Undo CTRL+Z Undo the last action.
Redo CTRL+Y Redo the last action.
Cut CTRL+X Cut the selected text string to the clipboard.
Copy CTRL+C Copy the selected text string to the clipboard.
Paste CTRL+V Paste the text string previously cut or copied to the clipboard.
Delete DELETE Delete the selected text string.
Select All CTRL+A Select the whole text contained in the Edit window.
Upper CTRL+SHIFT+U Convert the selected text string to uppercase letters.
Lower CTRL+SHIFT+L Convert the selected text string to lowercase letters.
Find CTRL+F Open the Find dialog to enter a search string and specify search options (case sensitive and/or whole word only) and the search direction backward (scrolls up in the source) or forward (scrolls down in the source).

By default, the currently selected text string is entered in the Find dialog.

Find Next F3 Find the next occurrence of the search string specified in the Find dialog.
Replace CTRL+H Open the Replace dialog to enter a Find search string and a Replace text string and specify search options and the search directory as described for the Find dialog.

By default, the currently selected text string is entered in the Find dialog.

Replace Next CTRL+F3 Replace the next occurrence of the search string specified in the Replace dialog.
Go To CTRL+G Open the Go To dialog to place the cursor on the source line entered in the dialog.
Print CTRL+P Output the text on a printer.
Check --- Applies to Natural sources only.

Check the syntax of the source.
Catalog --- Applies to Natural sources only.

Catalog the source.
Stow --- Applies to Natural sources only.

Check the syntax and catalog the source.
Macro --- Applies to macro sources only.

See Special Editor Functions for Macro Sources.

Test --- Applies to macro sources only.

See Special Editor Functions for Macro Sources.

Editing Macro Sources for Dynamic JCL Generation

Jobs with JCL location Macro Natural source (MAC) use the Entire Operations MACRO facility, which allows the use of variables anywhere in the JCL. Dynamic generation of JCL refers to the automatic substitution of these variables with their current values either when the job network is activated or when the job is submitted. The same job can thus have different job cards for different activation.

Dynamic JCL can be defined for jobs using the edit function in the Job Maintenance facility of Entire Operations. To convert existing JCL to the Entire Operations MAC format, use the JCL-IMPORT function in the job definition with JCL location as NAT (Natural source). In all cases, the Macro editor function must be used to generate the final JCL. The Test editor function can be used to test the generated JCL.

Note:
The Test function activates only job and network symbol tables, i.e., the macro test may fail with symbol not found but still run successfully when executed by monitor during loading of active JCL, when more symbol tables (e.g., calling symbol tables) are available.

This section covers the following topics:

Special Editor Functions for Macro Sources

The following special editor functions are available for a macro source:

Function Description
Macro Compile the macro JCL into an executable Natural object. This object will be executed by Entire Operations during JCL load. It will generate the executable active JCL. (This command is similar to the STOW command used for standard Natural programs.)

Note:
The Macro function can be executed in batch mode, e.g., for whole networks.

See also Bulk Execution of MACRO Commands.

Test Generate object for testing purposes. The generated JCL will show up in a new window.

Notes:

  1. The macro source is not saved during execution of the Macro function.
  2. The generated object is not compiled with the Natural STOW command during execution of the Test function.
Run Number used for the Test Function

The reserved run number used during the Test function is -3. During Test, a temporary active symbol table with this run number will be used. This avoids any influence on the defined master symbol table. In the log display, this reserved run number will not be displayed.

Escape Character for Natural Source Lines

Natural source lines must be preceded by the activation escape character of the job (see Symbol Escape Characters in the section Symbol Table and Symbol Maintenance).

The activation escape character at the beginning of a line distinguishes the line as a Natural statement from the JCL. The use of Natural statements provides full Natural functionality in dynamic JCL, including access to Adabas and Entire System Server. This means you do not need to learn any special control statements. All Natural statements used in dynamic JCL must be coded in structured mode.

Variables are user-defined and can be used in any part of the JCL, including the file name and control card. Variables are distinguished in the JCL by preceding them with an escape character: the activation escape character denotes variables to be substituted at activation time; the submit escape character denotes variables to be substituted at job submission time (see Symbol Escape Characters in the section Symbol Table and Symbol Maintenance).

Note:
These escape characters can be changed by the system administrator. However, this should only be done if absolutely necessary, for example for countries with a different alphabet. It is not advisable to use escape characters which have a defined meaning in a particular operating system or which are already defined as escape characters, e.g., $ in BS2000 or UNIX.

Parameter List

Each JCL for a job with JCL location Macro Natural source (MAC) must start with the declaration of the common user exit parameter list NOPXPL-A. The parameter P-CALL-PLACE (see the section User Exits) will contain MAC: 

§ DEFINE DATA PARAMETER USING NOPXPL-A

The first character (here: §) is the activation escape character of the job.

Variables in Dynamically Generated JCL

You can use four types of variables:

  • A variable from the symbol table specified for the job;

  • A variable from the parameter section (P-...);

  • A local variable defined in this Natural program, which can be computed in your program (L-...);

  • A Natural system variable (TIME, DATE, etc.) which is distinguished by an asterisk (*), for example, *TIME and *DATE.

Note:
All variables with prefixes other than P-, L- or * are assumed to be found in the symbol table. Symbol replacement itself (without embedding Natural statements) is also available for standard JCL (JOB (Standard Job) type jobs). See Symbol Replacement in the section Symbol Table and Symbol Maintenance.

This section covers the following topics:

Sample JCL

The following sample JCL illustrates the use of variables in the dynamically generated JCL of a job with JCL location Macro Natural source (MAC): 

§ DEFINE DATA PARAMETER USING NOPXPL-A
§ LOCAL    /* ... ALL LOCALS SHOULD START WITH 'L-'
§ 1 L-01    (A30)
§ 1 CLASS   (A01)     /* FROM SYMBOL TABLE, FOR #GET-SYMBOL
§ END-DEFINE
§ * ------------------------------------
#GET-SYMBOL CLASS
§ COMPRESS P-NETWORK P-JOB INTO L-01
//SNNOPEX  JOB  ,§P-OWNER,MSGCLASS=§MSGCLASS,CLASS=§CLASS
//STEP01   EXEC PGM=NOPCONTI,PARM='C=0004'
//STEPLIB  DD   DISP=SHR,DSN=§STEPLIB
//* DEVICE: §*DEVICE, INIT-USER: §*INIT-USER, TIME: §*TIME
//* L-01  : §L-01
§ IF CLASS = 'K'      /* SYMBOL USED IN STATEMENT -> #GET-SYMBOL
//* THE CLASS IS §CLASS
§ ELSE
//* ANOTHER MSGCLASS FOUND
§ END-IF
//*

The variables used in the JCL are assumed to have the following current values:

Symbol Table Variables
STEPLIB NOP.SYSF.DEV.LOAD
CLASS K
MSGCLASS X
Natural System Variables
*DEVICE BATCH
*INIT-USER  EORMON
Variables from the Parameter Section
P-NETWORK EX131A
P-JOB  EX-1-24
P-OWNER  SN

When the job is activated, Entire Operations substitutes the variables with their current values. The following JCL is generated as a result: 

//SNNOPEX  JOB  ,SN,MSGCLASS=X,CLASS=K
//STEP01   EXEC PGM=NOPCONTI,PARM='C0004'
//STEPLIB  DD   DISP=SHR,DSN=NOP.SYSF.DEV.LOAD
//* DEVICE: BATCH, INIT-USER: EORMON
//* L-01  : EX131-A EX-1-24
//* THE CLASS IS K
//*

#GET-SYMBOL

#GET-SYMBOL can be used within macro JCL to put an active symbol value into a local variable.

The symbol is taken from where it is found first in the symbol search path.

The syntax is as follows:

#GET-SYMBOL variable [value]

value is optional. If it is not specified, the variable will be filled with the contents of a symbol with the same name.

value must be of format A (alphanumeric). To convert value to a numeric field, use the Natural VAL system function. 

#GET-SYMBOL variable(index)

With this syntax, an instance of a multiple value symbol can be obtained. The variable must be defined as a local array with a sufficient array size.

Example:

#GET-SYMBOL L-SYMBOL(L-IND)

#SET-SYMBOL

#SET-SYMBOL can be used within macro JCL to set an active symbol and its value from a local variable or string.

The symbol will be set in the active symbol table which belongs to the active job.

For #SET-SYMBOL, a job must have a locally defined symbol table.

The syntax is as follows:

#SET-SYMBOL symbol [value]

value is optional. If it is not specified, the symbol will be filled with the contents of a local variable with the same name.

#SET-SYMBOL -M

#SET-SYMBOL can be used within macro JCL to set a master symbol and its value from a local variable or string.

The symbol will be set in the master symbol table which belongs to the active job.

For #SET-SYMBOL-M, a job must have a locally defined symbol table.

The syntax is as follows:

#SET-SYMBOL-M symbol [value]

value is optional. If it is not specified, the symbol will be filled with the contents of a local variable with the same name.

The value may contain symbols itself. Refer to the examples in the following section.

General Notes

Text strings must not contain blanks.

Blanks are used as separators for the parameters of #GET-SYMBOL and #SET-SYMBOL.

Examples of Using the Activation Escape Character

The activation escape character is §.

Statement Description
#GET-SYMBOL J Move the contents of symbol J to the local variable J.
#GET-SYMBOL #J §BB Move the contents of symbol BB to the local variable #J.
#GET-SYMBOL #J '§BB'  Move the contents of symbol BB to the local variable #J.
#GET-SYMBOL L-MULT '§?MV<M1,§I>' Move the result of a symbol function call into the local variable L-MULT.
#SET-SYMBOL J Set the active symbol J to the contents of the local variable J.
#SET-SYMBOL I #A  Set the active symbol I to the contents of the local variable #A.
#SET-SYMBOL AA 'text' Set the active symbol AA to the value text.
#SET-SYMBOL BB §I Set the active symbol BB to the contents of symbol I.
#SET-SYMBOL BB '§I' Set the active symbol BB to the contents of symbol I.
#SET-SYMBOL CC '§D.§E'  Concatenate symbol values of D and E, and put the result into the active symbol CC.
#SET-SYMBOL-M DD 'value' Set the master symbol DD to the value value.
#SET-SYMBOL-M TAGYYMMDD '&!D<T,YYMMDD>' Sets the result of the symbol function &!D<T,YYMMDD> (e.g. 150211) into the master symbol TAGYYMMDD.

Inserting Text Objects into JCL

You can insert Natural text objects anywhere in your JCL.

This feature is not limited to jobs with JCL location MAC (macro Natural source), but can also be used from within standard JCL.

The meta commands described here will be stripped from the active JCL and the submitted JCL.

The syntax is as follows:

#EOR-INCL LOC=NAT LIB=library MEM=text-object
Parameters of the #EOR-INCL Statement
Parameter Description
LOC  Location

NAT

Natural text object.

This is the only location which is currently allowed for text objects.

LIB  Library of the text object.
MEM  Name of the text object.

If the text object cannot be read, the JCL generation will be aborted with an error message.

Symbol replacement is possible within the #EOR-INCL statement.

Parameters for Included Text Objects

You may invoke included text objects with specific parameters.

For each parameter you want to pass to the text which is included by a #EOR-INCL statement, you must code a #EOR-PARM line in front of the #EOR-INCL statement.

These parameters will be in effect only for the text included (and all nested inclusions) in the following #EOR-INCL statement.

The syntax is as follows:

#EOR-PARM parameter = value [parameter = value]...

Multiple parameters can be passed on the #EOR-PARM line. This is limited by the line size.

Parameter values implicitly have the format A (alphanumeric).

Parameter values may contain blanks. In this case, they must be included in apostrophes (' ') or double quotes (" ").

Nested (Recursive) #EOR-INCL Statements

You may use nested #EOR-INCL statements inside text objects which have already been included. These nested inclusions may have their own parameter lists.

Note:
Be aware that the total number of inclusions for a JCL is limited by the Natural editor buffer size for the Natural task executing.

Replacement of Parameters within the Text Object

Parameters for text objects can be used within the included text object like any other symbol. They have precedence over the symbols of the current symbol table of the job (and the other symbol tables in the search hierarchy).

Therefore, parameters for included text objects can temporarily override symbols with the same name. The scope of a parameter is only the included text object, and the text objects which are invoked from within this text object by nested calls.

The lifetime of parameters defined via #EOR-PARM is JCL load time only. Normal symbol replacement can be used within included text objects like everywhere else in the JCL.

Examples of #EOR Statements

Example 1:
...
#EOR-INCL LOC=NAT LIB=JCLLIB MEM=§OBJECT
...

Include the Natural text object the name of which is in the symbol OBJECT from the library JCLLIB.

Example 2:
...
#EOR-PARM DBID = 9
#EOR-PARM TEXT-1 = "a string with blanks"
#EOR-INCL LOC=NAT LIB=USERLIB MEMBER=BLOCK1
//* JCL statement
#EOR-PARM DBID = 10
#EOR-PARM TEXT-1 = "another string"
#EOR-INCL LOC=NAT LIB=USERLIB MEMBER=BLOCK1
...

Include the Natural text object BLOCK1 from the library USERLIB. The parameters DBID and TEXT-1 are passed to the text object with different values for the two invocations.

Locking of Natural Sources

If you start Natural with the profile parameter SLOCK set to PRE, a lock avoids that two or more users can concurrently edit a Natural source object from an Entire Operations, an Entire Operations GUI Client or within a native Natural environment.

If SLOCK is set to POST or OFF, no locking is performed but the Entire Operations editor detects that several users edit a source at the same time.

You can use the Natural system command UNLOCK to check or unlock locked Natural source objects.

For detailed information on SLOCK and UNLOCK, refer to the relevant sections in the Natural Parameter Reference documentation.

Additional Prerequisites for Source Locking

  • In a UNIX or Windows environment, the Natural Development Server must be installed in the current Natural FNAT system file.

  • If you want to avoid concurrent source editing among users in a local Entire Operations GUI Client environment, in addition to Natural, you also have to start the Natural RPC server with SLOCK set to PRE.