Symbols are replaced during network or job activation or during job submission:
Symbols starting with the activation escape character are resolved during JCL loading, as part of the job activation.
Symbols starting with the submission escape character are resolved during job submission.
Note:
If a symbol replacement error occurs at submission time, the
event JNR Job not run - JCL error will be set to
occurred. If the event JNR is not defined, it will be added to the
active job.
Note for BS2000:
BS2000 SYSJV references (for example, &($SYSJV.TSN)
are no longer treated as Entire Operations symbols, regardless of whether they
are prefixed with an ampersand (&) denoting an activation
escape or submission escape character.
This document covers the following topics:
In JCL and Natural macro sources, the symbols to be substituted must be preceded by an escape character.
You can use different escape characters to determine whether symbol replacement is performed during JCL generation or job submission.
The following escape characters can be used in parallel in your Entire Operations environment:
Symbols preceded by the activation escape character are replaced at activation of a network or job.
If a JCL file contains the activation escape character, a symbol replacement is performed:
During JCL editing (temporary, using the symbol table master).
During JCL loading (permanently, using the active symbol table).
Symbols preceded by the submission escape character (also called submit escape character) are replaced during submission of a job. They can be used to pass symbol values that cannot be specified earlier when the job is activated.
Both activation escape and submission escape characters can be defined as system-wide defaults in the Entire Operations default settings (see Defaults for Network Options in the Administration documentation). However, different escape characters can be used for each job, if necessary.
You can also specify escape characters in your JCL or macro source. See also Defining Escape Characters.
Caution:
If you change escape character definitions for existing JCL,
symbols to be replaced can no longer be detected. In this case, consider
defining escape characters in your JCL or macro source.
This section covers the following topics:
We recommend that you use the following escape characters:
| Operating System | Escape Characters |
|---|---|
| z/OS | § (section sign) and $
(dollar sign).
|
| z/VSE | § (section sign) and #
(number sign).
|
| BS2000 | ^ (circumflex accent) and `
(grave accent).
Do not use |
| UNIX, Windows | No recommendation, except for UNIX:
Do not use |
Caution:
We strongly recommend that you do not define escape
characters already used by other (operating system specific) JCL features, for
example, parameters for DO procedures and SUBDTA characters in BS2000.
This section describes the options provided to define your default activation and submission escape characters.
Default Settings
The Network Options page of the Entire Operations Defaults function (see the Administration documentation) is used to define the default for all networks in your Entire Operations environment.
On the Operating System Specials page, you can also define the default escape characters for each operating system.
Network Definition
Defines the default escape characters to be used by all jobs of a network.
Job Definition
Defines the default escape characters to be used by an individual job.
Definitions in JCL and Macro Sources
In JCL and Natural macro sources, the symbols to be substituted must be preceded by an escape character.
You can define default escape characters in Entire Operations JCL or macro sources by coding one or both of the following meta statements as the first source line(s):
#EOR-ESC-ACT = activation-character #EOR-ESC-SUB = submit-character
For example:
#EOR-ESC-ACT = § #EOR-ESC-SUB = ^
The #EOR-ESC-ACT =
activation-character meta statement is
evaluated when the JCL containing this statement is loaded.
activation-character replaces the
current activation escape character in the current file. This replacement
influences symbol replacement only, not a meta statement defined in a macro
(Natural statement). The #EOR-ESC-ACT meta statement is removed
from the active JCL after loading.
The #EOR-ESC-SUB =
submission-character meta statement is
evaluated during job submission.
submission-character replaces the
current submission escape character in the current file. This replacement
influences symbol replacement only, not a meta statement defined in a macro
(Natural statement). The #EOR-ESC-SUB meta statement is kept in
the active JCL after loading.
Both meta statements are logged when they are evaluated during JCL loading or job submission.
If you add a meta statement to a Natural macro source, you
must recatalog the source with the MACRO command.
Note about Trigraphs:
Trigraph
encoding uses question marks (?) as escape characters
in the JCL definition. You can avoid decoding conflicts by
switching trigraph encoding off and
on in the JCL as described in Trigraph Encoding for JCL
Submission on UNIX and Windows.
Entire Operations provides a standard method for symbol prompting to
replace symbols during network activation. Standard symbol prompting is not
used in jobs of the type NET
(subnetworks).
If any of the activated jobs are jobs with JCL location
MAC or jobs
of the type JOB whose JCL
contains symbols for variable values, these symbols are replaced by their
current values during the manual activation, except those that are defined to
be replaced at submission time.
In a job network definition and in the subsidiary jobs, several symbol tables can be defined. During a network or job activation, all symbol tables are prompted sequentially, which contain at least one symbol to be prompted.
Notes:
EOR1830 - More than :1: Symbol Tables
in Network will be shown as a warning if the network uses more
symbol tables. In this case, some symbol table might not be prompted. If symbol
table versions are used, the determination of the current symbol table version
might not work properly.
To modify and confirm symbols and save the active symbol table as a
file
Activate a network with at least one symbol defined for prompting.
A Symbol Prompting window like the example below opens:
The window lists all symbols defined for prompting during network activation and the symbol table master that contains the symbols.
In the example above, different symbol tables are
used for prompting: EXAM-TABLE is defined for the
SAG-PROMPT network and EXAM-TABLE <T-V1> is
defined for a job contained in the network. The CLASS symbol from
EXAM-TABLE is listed twice because two multiple values
(20 and 7) are defined for this symbol. The
description defined for the EMAIL symbol is shown in the
Description of selected symbol section. In this example,
the SAG-PROMPT network is activated for Run 112.
You can add new symbols, modify existing symbol values or leave them unchanged.
If you want to change symbol parameters not listed in the Symbol Prompting window (for example, the format of a symbol), select the required symbol from the table and choose Modify to open a Maintenance Symbol Active window for this symbol. The fields in this window are explained in Fields: Symbol.
The columns contained in the window are explained in Columns: Symbol Prompting, all options and functions provided in the window are explained in Options and Functions: Symbol Prompting.
Note:
If a validation check is defined for
the symbol, you can only enter a valid symbol value. Incorrect values are
rejected, and a user-defined error message is issued.
Choose Continue when you are finished.
If Save active symbol table as file and Symbol printing after prompting is selected in your user profile (see in the Administration documentation), a window opens for entering file specification parameters: see To save an active symbol table in the section Saving Symbol Table Information as a File.
If a workplan is defined for the network and Show workplan after activation is selected in your user profile (see GUI General in the Administration documentation), a Workplan window opens.
Network activation starts after the last window closes.
The new symbol values remain in the symbol table until the symbol table is modified specifically or until the next prompting after manual activation of a job network that uses the symbol table.
This section covers the following topics:
The columns of the Symbol Prompting window are explained in the following table:
| Column | Description |
|---|---|
| Symbol Table | Name and version (if defined) of the symbol table master that contains the symbol. |
| Symbol | Name of the symbol defined for prompting. |
| Value | Value of the symbol defined for prompting. |
The options and functions provided in the Symbol Prompting window are explained in the following table:
| Option/Function | Description |
|---|---|
| Add | Add a new symbol for the symbol table
selected in the window.
A Create new Symbol Active window opens for the selected symbol table. The fields and tabbed pages in this window are explained in Fields: Symbol. |
| Modify | Change symbol parameters not listed in
the Symbol Prompting window (for example, the format).
A Maintenance Symbol Active window opens for the selected symbol. The fields and tabbed pages in this window are explained in Fields: Symbol. |
| Description of selected symbol | Shows the descriptive text of the symbol currently selected in the Symbol Prompting window. |
| Save active symbol table as file | Select this option if you want to save the active symbol table as a file after network activation. |
To display the description defined for a prompted symbol
In the Symbol Prompting window select the table row that contains the symbol whose description you want to display.
The descriptive text is then displayed in the
Description of selected symbol section of the
Symbol Prompting window. In the
example of the window,
the description that belongs to the EMAIL symbol is shown.
Text is only available if it has been entered in the Prompt Text field of a symbol definition (see Fields: Symbol).
To repeat symbol prompting from the beginning
Choose or to cancel the current network or job activation.
Start the activation again.
You can specify a customized user exit routine that defines your own validation checks and help information for symbol prompting. This can be used to modify active symbols depending on the values of other symbols, or of anything else.
You can then adapt a symbol table during each job run with or without using a window that prompts you for input. If you do not use a prompt window, the symbol table is adapted automatically in the background.
For details on defining user exit routines, see User Exits for Validation Checks of Symbol Values in the section User Exits.
To specify a user exit for symbol modification
In a Network Master window, open the tabbed page Symbol Prompting:
Specify the type of symbol prompting by defining the Natural library and the respective user exit routine. The fields are explained in Fields: Symbol Prompting User Exit.
Choose when you are finished.
This section covers the following topics:
The input fields of the Symbol Prompting page are described in the following table:
| Field | Description | |
|---|---|---|
| Natural Library | Name of the Natural library where the symbol prompting user exit resides. | |
| User Exit | Name of the symbol prompting user exit. | |
| Symbol Modification | Symbol modification
option(s).
Possible check box settings: |
|
| during prompting
(checked) |
A prompt window opens (default).
You are asked to modify or confirm symbols defined for prompting for the active symbol table. See also Example of an Active Symbol Table List. |
|
| in Background
(checked) |
No prompt window opens.
The symbol modification is managed by the user exit routine which runs in the background. |
|
| (both boxes checked) | Performs both modification options:
A prompt window opens first and then symbol modification is managed by the specified user exit. This allows you to set other symbols which are dependent on prompting. |
|
The following is an example of an output file generated for an active symbol table using Entire Operations GUI Client:
The file lists the current status of the symbols defined for the
symbol table EXAM-TABLET-V3 which is prompted when the network
SAG-PROMPT is activated.
Notes:
no symbol table defined is
issued.
This section covers the following topics:
The types of symbol tables available and the search order used to find and replace symbols in symbol tables are described in the following section.
Entire Operations first searches for a symbol in the active
user-specific symbol table. After this, it searches in the user-defined symbol
table master, in the network default symbol table, and finally in the
system-wide symbol table. If it searches for the symbol in a subnetwork, the
symbol tables of the calling job of the type
NET as well as the symbol tables of the superior job
networks are searched (in ascending order) if necessary.
| Symbol Table Type | Description |
Search |
|---|---|---|
JA
(Job active) |
Active symbol table referenced by the active job. | 1 |
NA
(Network, active) |
Active symbol table referenced by the network. | 2 |
CA
(Calling job) |
Active symbol table referenced by the
calling job.
This only applies if the active job is within a subnetwork. Depending on the subnetwork nesting level, several symbol tables of calling jobs can be searched. The search operation can repeat in ascending order. |
3 |
CN
(Calling network) |
Active symbol table referenced by the
calling network.
Depending on the subnetwork nesting level, several symbol tables of calling networks can be searched. The search operation can repeat in ascending order. |
4 |
JM
(Job master) |
Symbol table referenced by the job master. | 5 |
NV
(Network version) |
Symbol table referenced in the network version. | 6 |
OD
(Owner default) |
Symbol table master
owner/A.
The symbol table
|
7 |
SD
(System default) |
Symbol table master
SYSDBA/A.
The symbol table |
8 |
Note:
If you invoke the link to the symbol table(s) in the object
network, job master or active job, you will get a list of all
usable symbol tables
for this object in the hierarchical order described above.
The following actions are triggered as soon as a symbol cannot be found in any symbol table:
- A message is written to the log
A message is written to the system log file (see Log Information), for example:
Symbol XYZ not found ... Symbol Table EXAMPLE/SYMTAB1The logged symbol table (here:
SYMTAB1) is the first symbol table searched upward in the symbol table hierarchy. Example: If no symbol table has been defined at the job level, the symbol table defined for the network is logged.
- A global message is sent
A
symbol not foundmessage containing the name of the searched symbol table is sent if the Global Message Sending Exit (see the Administration documentation) is enabled in your environment.- A global message is saved in the event store
An appropriate message including the name of the searched symbol table is saved in the event store if the Symbol not found and Event Store options of the Global Messages and Exits function (see the Administration documentation) are enabled in your environment.
- The problem is handled by a global user exit
A user exit takes action for the missing symbol to resolve the problem and continue processing if the Global Symbol Not Found Exit (see the Administration documentation) is defined and enabled in your environment.
- Current processes are aborted
Current operations (for example, JCL loading) are terminated if a problem with missing symbols cannot be resolved.
Symbols can be used within other symbols (nested).
For nested replacement of symbols, the following rules apply:
On the top level, only the escape character defined for the job or network is checked and replaced.
If the activation escape character is used on a nested level, only activation escape characters are replaced on deeper levels. This is necessary to prevent too early replacements of submission escape characters.
If the submission escape character is used on a nested level, submission and activation escape characters are replaced on deeper levels.
- Example of Nested Replacement
Symbol Value PREFIXEORSTEPLIB§PREFIX..EXAMPLE.LOAD
§STEPLIBis replaced byEOR.EXAMPLE.LOAD.Note:
If a point marks the end of a symbol, it is deleted on replacement. With nested replacement, the deletion takes place replacement by replacement. Thus, a sufficient number of points must be coded. If a point is to remain at the end of the symbol, two points must be coded.- Example of Nested Symbol Replacement in JCL
changes to the following when
J=20andJJ=§J.01:/* IN 2001 SOFTWARE AGThe advantage of this method is that symbol replacement is performed within the fixed positions.
For symbol replacement in JCL submitted on mainframes (z/OS, z/VSE and BS2000), the following particularities apply:
| Column 72 contains one blank and the columns 73 to 80 contain digits. | Columns 71 to 80 of the line are saved before the first replacement, and they are written back after the last replacement. |
Column 72 contains a hyphen (-) and the
columns 73 to 80 contain blanks.
|
Columns 71 to 80 of the line are saved before the first replacement, and they are written back after the last replacement. |
Column 71 contains a comma (,) and the
columns 72 to 80 contain blanks.
|
Columns 71 to 80 of the line are saved before the first replacement, and they are written back after the last replacement. |
| Intermediate results | Intermediate results can even be longer than 71 characters. They are only overwritten by possibly saved strings at the end of the replacement as a whole. |
Avoid the equal sign (=) within a symbol value. This
causes problems during import or export operations of symbol tables.
Symbols to be replaced are detected by a preceding escape character anywhere in the JCL. See Symbol Escape Characters for details and Example of Nested Symbol Replacement in JCL.
Symbol names end with one of the following delimiter characters:
blank ( ), comma (,), semicolon
(;),
period (.), apostrophe ('),
commercial at (@),
percent sign (%), logical not (¬),
ampersand (&),
parenthesis (( or )), or equal
sign (=).
Example: §SYMBOL-1;.
A single period (.) after a symbol is removed during
replacement. But two consecutive periods (..) are converted to one
period (.). This is important for the dynamic creation of file
names.
The following algorithm is used for symbol replacement:
Search for the symbol farthest to the left.
If none (or no more) available -> end.
Replacement
In case of error -> end.
Write updated line.
Continue at (1).
This makes nested symbol replacement (symbols within symbols) possible.
This section applies to JCL submitted on mainframes only.
Multiple symbol replacement can cause a shift within a line. However, in the following cases, parts of the line are kept in a fixed position:
Symbols do not follow one another directly.
The columns 72 to 80 always remain fixed. If the column 70 contains a blank and column 71 a comma, then these will also remain fixed.
If a symbol is followed by at least two blank spaces, the rest of the line is kept in its original position, unless the symbol value would overlap with it. For example:
/FILE ABC.§VAR COMMENT
changes to the following when VAR =
REPLACE:
/FILE ABC.REPLACE COMMENT
If a symbol is followed directly by continuous text, then by
at least two blank spaces, then by an exclamation mark (!) and
continuous text: the symbol is replaced and the exclamation mark
(!) is replaced by blank spaces. For example:
/FILE ABC.§VAR..XYZ !COMMENT
changes to the following when VAR =
REPLACE:
/FILE ABC.REPLACE..XYZ COMMENT
If you want to replace a symbol with multiple values when a job is
activated numerous times concurrently, you must use P-SUFFIX to
identify the variable to be replaced. This is the variable you entered in the
Suffix
Symbol field in the Job Master Definition window
(see the field description in the section Job Maintenance).
For information on defining multiple symbol values, see the symbol
functions !MV or
?MV and !MM or ?MM described
in the section Functions for Symbol Replacement.
Note:
If Suffix Symbol contains no values, then
the multiple job is activated as a temporary dummy job.
You can obtain a specific occurrence of a multiple-value symbol by
using the symbol function
!MV or ?MV.
If you want to enter symbols in subnetworks as well, you can attach a symbol table to the main network; this table contains all symbols to be queried in the jobs of the subnetwork(s). At the same time, the symbol table can be linked to the corresponding jobs of the subnetwork(s) by means of symbols whose values are not to be retrieved. After symbol entry, this creates active symbol tables attached to the main network.
On the job level, Entire Operations tries to load the symbols from the level(s) above if a symbol with the corresponding symbol table is not found, for example from the active symbol table of the main network. Entire Operations does not create active symbol tables on subnetwork job levels as the run numbers are not yet known at the time of the main network's activation and as symbol prompting is activated first.