Defining Symbols and Symbol Values

This document covers the following topics:

• Listing Symbols of a Symbol Table

• Displaying a Symbol Definition

• Adding a Symbol Master

• Copying a Symbol within a Symbol Table or to another Symbol Table

• Modifying Symbols in a Symbol Table

• Defining Multiple Symbol Values

• Specifying a Range Check for Numeric Symbol Values

• Reserved Symbols

• Predefined Symbols

• Symbols in Node Definitions

• Validating Symbol Values with a User Exit

• Global Symbol Modification Exit

• Symbol Setting triggered by the SYSOUT of a Job

• Deleting a Symbol from a Symbol Table

Listing Symbols of a Symbol Table

To list symbols for a selected symbol table

• Type L in the line command input field of the selected symbol table in the Master Symbol Tables window. Press ENTER.

  A Master Symbol Table screen appears.

  The screen lists all symbol masters defined for the selected symbol table master.

  The columns on the screen are explained in Columns: Symbol Table Master.

Displaying a Symbol Definition

To display a symbol definition

1. On the Master Symbol Table screen, type L in the line command input field next to the required symbol. Press ENTER.

   The Master Symbol Browsing window opens in the same format as the Master Symbol Addition window (see also Adding a Symbol Table Master).

2. Choose PF3 (End) to return to the Master Symbol Table screen.

Adding a Symbol Master

To add a symbol to a symbol table

1. On the Master Symbol Table screen, choose PF2 (Add).

   The Master Symbol Addition window opens (see Adding a Symbol Table Master), with the name of the master symbol table already entered in the Symbol Table field. This field is not modifiable.

2. Enter the new symbol definition.

3. Choose PF5 (Save) to save the new definition.

4. Press PF3 (End) to return to the Master Symbol Table screen.

Copying a Symbol within a Symbol Table or to another Symbol Table

To copy a symbol definition within a symbol table or to another symbol table

1. On the Master Symbol Table screen, type C in the line command input field next to the symbol you want to copy. Press ENTER.

   A Symbol Copy window similar to the example below opens:

   19.12.13 ***** Entire Operations ***** 14:10:24 Owner SN Master Symbol Table A-1 Version v12.44 Network +----------------------------------------------------------+ ------- ! ! --------- C Symbo ! Symbol Copy ! *---- ! From ! _ ABCD ! Symbol ==> SHORT1__________________________________ ! .13 15:25 _ FILE- ! Owner ==> SN________ Network ==> __________ ! .13 09:27 _ MULT- ! SymTab ==> A-1_______ Run ==> _____ ! .13 09:35 _ NUM-1 ! Version ==> v12.44____ ! .13 10:19 c SHORT ! ------------------------------------------------- ! .13 09:26 _ TEST ! To ! .12 15:03 _ Z1 ! Symbol ==> SHORT2__________________________________ ! .13 16:44 _ Z2 ! Owner ==> SN________ Network ==> __________ ! .13 14:03 ! Symtab ==> A-1_______ Run ==> _____ ! ! Version ==> v12.44____ ! ! ! ! PF1 Help PF3 End ! +----------------------------------------------------------+ ******************************* Bottom of Data ******************************* C Copy D Delete L List M Modify Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Add End Copy Save Up Down Print

   The upper half of the window shows the origin symbol. In the lower half of the window you must define the target symbol. With this function, you may copy to another symbol in the same table, or to a symbol in another symbol table and / or symbol table version. If you leave the window with PF3 without specifying a target symbol name, the copy will be aborted.

2. Enter the name of the symbol to copy to in the To Symbol field.

3. Press PF3 (End) to copy the symbol and return to the Master Symbol Table screen.

Modifying Symbols in a Symbol Table

To modify a symbol definition

1. On the Master Symbol Table screen, type M in the line command input field next to the required symbol. Press ENTER.

   The Master Symbol Modification window opens in the same format as the Master Symbol Addition window (see Adding a Symbol Table Master). The window contains the current values and the Symbol Table and Symbol Name fields are not modifiable.

2. Change the text in the input fields as required.

3. Press PF5 (Save) to save the modified symbol definition.

4. Press PF3 (End) to return to the invoking location.

Defining Multiple Symbol Values

You can give a symbol several values which can be used in subsequent substitutions of the same symbol. These values can be used for the multiple parallel activation of a job. The number of parallel jobs is the same as the number of multiple values defined here. The maximum number of multiple values is 150.

To view and define multiple symbol values

1. Open a Master Symbol Modification or Active Symbol Modification window.

   If multiple values have already been defined for the selected symbol, the Value field indicates how many, for example: *** 25 multiple values ***.

2. Press PF9 (Mult).

   A Multiple Symbol Values screen similar to the example below opens:

   Multiple Symbol Values Owner EXAMPLE Network Symbol Table EXA-SYMBOL Run Version Version SV98 Symbol MULTI-SYMBOL-1 1 -------------------------- Values 1 to 13 ------------------------- 78 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa bbbbbbbbbbbbbbbbbbbb__________________________________________________________ ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc___________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ Enter---PF1----PF2----PF3--------PF5--------PF7----PF8----PF9----PF10--PF11--- Help Insert End Save Up Down Delete Left Right

3. You can view all current values and add, delete or modify values as required. Be careful when inserting or deleting a value. Lines are concatenated to one symbol value and stored as a single (long) field in the database.

   For valid input values, see also the descriptions of the Value field and the Numeric Range Check window in the section Columns: Symbol Table Master.

Note for Long Symbol Values

If a symbol value exceeds 78 characters (maximum is 120 characters), the value is truncated on the Multiple Symbol Values screen. In this case, you need to scroll data to the right using PF10.

All multiple values that exceed 78 characters have to be added and modified using Entire Operations GUI Client. You can only add or modify the first value listed on the screen (in the Master Symbol window).

This section covers the following topics:

• Special PF Keys: Multiple Symbol Values

• Symbol Replacement

Special PF Keys: Multiple Symbol Values

Symbol Replacement

You can use the symbol function !MV or ?MV (see Functions for Symbol Replacement) to get single occurrences of multiple-value symbols for replacement.

Specifying a Range Check for Numeric Symbol Values

You can guarantee that a numeric symbol value is within a specified number range.

To specify a range check for numeric symbol values

1. Open a Master Symbol Addition/Modification window for a symbol of the format N (numeric) and press PF8 (RgChk).

   A Symbol: Numeric Range Check window opens.

2. Enter the range of numbers (here: 1 to 30) to be used for the value check as shown in the example below:

   +---------------------------------------------------------------+ | | | Master Symbol Modification | | | | Symbol Table EXA-SYMBOL Owner EXAMPLE | | Version SV98______ Network | | Run | | Symbo +-----------------------------------------------+ | | | | | | | Symbol: Numeric Range Check | | | | | | | | Owner ===> EXAMPLE | | | | Symbol Table ===> EXA-SYMBOL | | | | Version ===> SV98 | e. | | | Symbol ===> NUM-1 | | | Pr | | | | Prom | Value from ===> 1_________ | | | | Value to ===> 30________ | | | | | | | | ---PF1--PF3---------PF5---------PF9---- | | | | Help End Save Delete | | | Enter- +-----------------------------------------------+ -- | | Help Add End Save RgChk Mult Copy Exit | +---------------------------------------------------------------+

   For valid input values and further information on range checking, see Numeric Range Check in the section Fields: Master and Active Symbols.

   Choose PF5 to save your entries.

3. If you then try to change the value of this symbol (or a multiple value of the symbol) to a value outside the specified range, an error message appears and the new value (here: 50) is not accepted:

   +---------------------------------------------------------------+ | EOR0160 - Range is 1 thru 30 | | Master Symbol Modification | | | | Symbol Table EXA-SYMBOL Owner EXAMPLE | | Version SV98______ Network | | Run | | Symbol Name NUM-1___________________________________ | | Format N | | Value 50______________________________________ | | ________________________________________ | | ________________________________________ | | Be careful with insertions or deletions. | | The lines will be concatenated to one symbol value. | | | | Prompting N Update Mode _ | | Prompt Text ________________________________________ | | ________________________________________ | | ________________________________________ | | ________________________________________ | | ________________________________________ | | Enter-PF1---PF2---PF3-----PF5----PF8----PF9---PF10---PF11-- | | Help Add End Save RgChk Mult Copy Exit | +---------------------------------------------------------------+

Reserved Symbols

Reserved symbols perform user-specified tasks. They can be changed as required if symbol table maintenance is allowed for the user (see Symbol Tables in Network Maintenance Functions in the Administration documentation).

Reserved symbols can be added, modified and deleted in symbol tables like all other symbols.

This section covers the following topics:

• Reserved Symbols for Command Line Parameters

• Reserved Symbols for Mainframe Platforms

• Reserved Symbols for FTP Jobs

• Reserved Symbols for Profile Scripts (UNIX)

• Reserved Symbol for Epilog Scripts (UNIX and Windows)

Reserved Symbols for Command Line Parameters

Passing Command Line Parameters

If you want to pass command line parameters for a job, use the reserved symbol CMDLINE-job in the job's symbol table, where job is the job name.

Several parameters, separated by blanks, can be contained in this symbol.

Example:

Job name:	JOB1
Member name in JCL definition:	STC001
Content of symbol CMDLINE-JOB1:	PARM1=Y,PARM2=N

The start command generated and issued by the Entire Operations Monitor is:

S STC001,PARM1=Y,PARM2=N

Command Line Passing to Shell Scripts in Entire Operations

• If a job is to be activated, Entire Operations checks whether a CMDLINE-job symbol exists.

  If such a symbol exists, its content is appended to the invocation of the job.B script.

• Nested (recursive) symbol replacement:

  The CMDLINE-job symbol can contain nested symbols.

  These can be prefixed by the activation escape character for activation time replacement, or by the submission escape character for submission time replacement.

• The job.sh resp. job.bat script (the user's script, with some Entire Operations header files), is not invoked directly, but out of the wrapping script job.nnnnnnnn.frame.sh resp. job.nnnnnnnn.frame.bat.

  nnnnnnnn denotes an 8-digit repeat count. For the first job submission, this is 00000000.

• The job.nnnnnnnn.frame.sh resp. job.nnnnnnnn.frame.bat script is generated by Entire Operations at submission time. On UNIX, this is always a Bourne shell script (starting with the shebang #!/bin/sh), regardless of the shell of the user's script.

• UNIX: Command line parameters must be passed in Bourne shell syntax. This means quoting and masking of special characters according to Bourne shell rules. Note that the Bourne shell script quotes from the parameters quoted in the invoked shell script.

• Use c:\\work\\test.txt to pass a windows file name, for example, c:\work\test.txt.

• The maximum total length of all parameters is 2000 bytes (including separating blanks) after symbol replacement.

• The maximum length of a single parameter is 240 bytes.

Reserved Symbols for Mainframe Platforms

The symbols JCL-NODE, SUBMIT-NODE and SYSOUT-NODE are searched for in the symbols tables as described in Symbol Table Types and Symbol Search Order.

Reserved Symbols for FTP Jobs

There are some symbols which have a special meaning for jobs of the type FTP.

Wildcards mean than all symbols starting with the mentioned prefix are reserved.

Reserved Symbols for Profile Scripts (UNIX)

This section describes the reserved symbols used when generating UNIX frame scripts (job.current.frame.sh) that source profile scripts as described in UNIX: Usage of Profile Scripts in the section Job Maintenance.

The reserved symbols are defined with Format A.

Reserved Symbol for Epilog Scripts (UNIX and Windows)

This section describes the reserved symbol used for executing epilog scripts for UNIX or Windows jobs.

Symbol Table Search for Epilog Scripts

Entire Operations searches for NOP-EPILOG-execution_node in the symbol table hierarchy each time a job is submitted on a UNIX or Windows execution node.

The epilog script is not executed if NOP-EPILOG-execution_node cannot be found in any symbol table or if the value supplied with the reserved symbol is empty, contains a dash (-) or is set to NO.

If the reserved symbol is contained in the topmost symbol table (SYSDBA/A), the respective epilog scripts is executed for all UNIX and Windows jobs, except for those that reference a reserved symbol contained in a lower-ranking symbol table.

Using Epilog Scripts

The shell script defined with NOP-EPILOG-execution_node must have executable rights.

The epilog script is invoked by the defined JCL frame script and starts to execute when the main script terminates.

If an epilog script is defined but cannot be found, the exit code of the job is set to 102 so that the whole job ends in error.

The epilog script does not accept any parameters. The epilog script can obtain information from environment variables set in the JCL frame script by using reserved symbols (see Reserved Symbols for UNIX and Windows Environment Variables).

Symbol replacement is not performed for the epilog script. The epilog script is directly executed by the frame script, without intermediate storage in Entire Operations.

A Windows epilog script must not end with an exit statement. Set an exit code as follows:

set errorlevel=exit_code

If the exit code defined in the epilog script is higher than the exit code of the frame script, the exit code of the main script is set to the exit code of the epilog script.

Predefined Symbols

Predefined symbols perform special-purpose tasks for example, within JCL files or scripts. They are defined by Entire Operations and cannot be modified.

All symbol names starting with an asterisk (*) or P- are reserved for predefined read-only symbols. These prefixes must not be used for user-defined symbols.

Predefined symbols must not be defined in symbol tables.

• Table of Predefined Symbols

• Predefined Symbols for Multiple and Parallel Activations

• Predefined Symbols for Subnetworks and Recovery Jobs

Table of Predefined Symbols

The following symbols are read-only. They can be used without defining them in a symbol table.

For further explanations of date and time formats, see also Date and Time Formats.

P-JCL-FILE = e:/sag/nop/jcl/job1.bat 

type +F+&P-JCL-FILE

e:\sag\nop\jcl\job1.bat

Predefined Symbols for Multiple and Parallel Activations

§ 1 P-MPA (A50) 
§ 1 REDEFINE P-MPA ... 
#GET-SYMBOL P-MPA

Predefined Symbols for Subnetworks and Recovery Jobs

The table below lists and describes the symbols a subnetwork or recovery job requires to communicate with its invoking network or the calling job, respectively.

These symbols have the value of a blank, unless they are used in a subnetwork or a recovery job.

§ 1 P-C-MPA (A50) 
§ 1 REDEFINE P-C-MPA ... 
#GET-SYMBOL P-C-MPA

Symbols in Node Definitions

In general, you can define all nodes used in network and job definitions as symbols. Extra rules and restrictions for particular nodes are described in the following section.

You can define a node as a symbol of up to 4 characters that is preceded by the activation escape character, for example, §NODE.

You can also use the predefined symbol PMPA preceded by the activation escape character, for example, §PMPA. See also Predefined Symbols in the section Symbol Table and Symbol Maintenance.

This section describes restrictions and special considerations that apply when using a symbol for a node:

• Using Symbols in Message Sending Nodes

Using Symbols in Message Sending Nodes

Symbol use for message sending nodes is currently only possible on the Entire Operations CUI client.

Warning: Using symbols for message nodes on Entire Operations GUI client can produce severe errors.

When using the activation escape character as a symbol prefix, the symbol is evaluated immediately and the message is sent at job activation time.

Validating Symbol Values with a User Exit

You can define a user exit to check the validity (plausibility) of symbol values during symbol modification or prompting.

For detailed information on writing a user exit, see User Exits for Validation Checks of Symbol Values in the section User Exits.

To check symbol values with a user exit

1. Press PF11 (Exit) in a Master Symbol Addition/Modification window.

   A Definition of Symbol Check Exit window similar to the example below opens:

   +---------------------------------------------------------------+ 14:16:50 | | . (unnamed) | Master Symbol Modification | n | +-------------------------------------------------------------------+ | Symbo | | | | Definition of Symbol Check Exit | | | | | Symbo | Owner ===> REQUEST | | | Symbol Table ===> P185905 | | | Version ===> | | | Symbol ===> LONG1 | | | | | | Library ===> ________ | | | Exit ===> ________ | | | | | Pr | ---PF1-----PF3---PF4---PF5---------PF9--------------------- | | Prom | Help End Edit Save Delete | | +-------------------------------------------------------------------+ | ________________________________________ | .02.00 17:16 | ________________________________________ | ************ | ________________________________________ | | Enter-PF1---PF2---PF3-----PF5----PF8----PF9---PF10---PF11-- | | Help Add End Save RgChk Mult Copy Exit | +---------------------------------------------------------------+

2. Enter or change the entries in the Library and Exit fields. The input fields are described in Definition of Symbol Check Exit in the section Fields: Master and Active Symbols.

3. Press PF5 (Save) when you are finished.

Special PF Keys: Symbol Check Exit

The PF keys available to edit or delete a user exit are described in the following tabe:

PF Key	Name	Function
PF4	Edit	Edit or create a user exit. Do not forget to STOW the routine so it can be used.
PF9	Delete	Removes the user exit from the selected symbol definition but keeps all related user exit objects in the library.

Global Symbol Modification Exit

For the active symbol modification, a global symbol modification exit (described in the Administration documentation) can be defined too. This global exit is only used if there is no specific exit defined on the network level. The global exit is called with the same parameter list as the exit on the network level.

Symbol Setting triggered by the SYSOUT of a Job

(Not applicable on mainframes)

It is possible to set symbols during a job’s End-of-Job checking, triggered by a meta command in the job’s SYSOUT. The meta command is EOR-SYMBOL.

With this meta command it is possible to set an Entire Operations symbol during the End-of-Job checking of a job.

The meta command is available for jobs running on UNIX or Windows.

The symbol will be set into the active job's active or master symbol table. If the active job has no active symbol table, the job result is set to not ok.

Syntax:

Sets an active symbol.

Sets a master symbol.

The meta command can be generated, for example, with an echo command:

echo "EOR-SYMBOL SA SYMBOL1=$HOSTNAME"

With HOSTNAME=pcsn this produces the SYSOUT line:

EOR-SYMBOL SA SYMBOL1=pcsn

During End-of-Job checking, the symbol SYMBOL1 in the job's active symbol table will be set to pcsn.

The echo command can be generated dynamically by using symbol replacement. Therefore, this kind of symbol setting is very flexible.

Example:

echo "EOR-SYMBOL SA PID.&*TIMN=$$"

creates the SYSOUT line:

EOR-SYMBOL SA PID.1131185=4837

Deleting a Symbol from a Symbol Table

The options provided to delete a symbol master or symbol active from a symbol table are described in the following section.

To delete a symbol from the master symbol table

1. On the Master Symbol Table screen, type D in the line command input field next to the symbol you want to delete. Press ENTER.

   A confirmation window opens.

2. Type in the symbol name to confirm deletion and press ENTER.

3. Press PF3 (End) to return to the Master Symbol Table screen.