Defining Symbols and Symbol Values

This document covers the following topics:

• Available Functions: Symbol Master

• Listing Symbol Masters

• Viewing a Symbol Master Definition

• Modifying a Symbol Master

• Adding a Symbol Master

• Maintaining a Symbol Active

• 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

Available Functions: Symbol Master

To list all functions available for a Symbol Master node

• In the object workspace, select a Symbol Master node and open the context menu.

  The following functions are available:

  Function	Shortcut	Description
  List	F8	See Listing Symbol Masters.
  New	CTRL+N	See Adding a Symbol Master.
  Refresh	F5	See Refreshing Object Lists.
  Filter	F3	See Filtering Objects.
  Paste data	CTRL-V	See Pasting Objects.
  Set Drag And Drop Function	---	See Drag & Drop.

To list all functions available for a symbol master

• From the Symbol Master node, select an instance and open the context menu.

  The following functions are available:

  Function	Shortcut	Description
  Open	CTRL+O	See Modifying a Symbol Master.
  Display	CTRL+D	See Viewing a Symbol Master.
  Delete	DELETE	See Deleting a Symbol from a Symbol Table.
  Copy data	CTRL+C	See Copying Objects.
  Set Drag And Drop Function	---	See Drag & Drop.

Listing Symbol Masters

To list symbol masters

• In the object workspace, select a Symbol Master node and choose List from the context menu, or press F8.

  A Symbol Master List window similar to the example below opens:

  

  The table contained in the window lists all symbol masters defined for the selected symbol table master (here: EXAM-TABLE).

  The columns in the window are explained in Fields and Columns: Symbol Table Master.

Viewing a Symbol Master Definition

To view a symbol master definition

1. In the object workspace, select a Symbol Master instance.

2. Open the context menu and choose Display, or press CTRL+D.

   A Display Symbol Master window opens with the current symbol definition.

   The read-only fields on the tabbed pages Main, Multiple Symbol Values and Value Check correspond to the fields and pages in the Maintenance Symbol Master window. They are explained in Fields: Master and Active Symbols.

Modifying a Symbol Master

To modify a symbol master

1. In the object workspace, select a Symbol Master instance.

2. Open the context menu and choose the Open function, or press CTRL+O.

   A Maintenance Symbol Master window similar to the example below opens:

   

3. Make your changes. The fields on the tabbed pages Main, Multiple Symbol Values and Value Check are explained in Fields: Master and Active Symbols.

4. Choose OK when you are finished.

   The symbol master is modified, stored and now ready to use in the active network.

Adding a Symbol Master

To add a symbol master to a symbol table

1. In the object workspace, select the Symbol Master node.

2. From the context menu, choose New, or press CTRL+N.

   A Create new Symbol Master window opens.

   The input fields on the tabbed pages Main, Multiple Symbol Values and Value Check correspond to the fields and pages in the Maintenance Symbol Master window. They are explained in Fields: Master and Active Symbols.

3. Enter a name for the symbol and make the required definitions.

4. Choose OK when you are finished.

   The symbol master is created and now ready to use in the active network.

Maintaining a Symbol Active

This section covers the following topics:

• Available Functions: Symbol Active

• Viewing a Symbol Active

• Adding a Symbol Active

• Modifying a Symbol Active

Available Functions: Symbol Active

To list all functions available for a Symbol Active node

• In the object workspace, select a Symbol Active node and open the context menu.

  The following functions are available:

  Function	Shortcut	Description
  List	F8	See Listing Objects.
  New	CTRL+N	See Adding a Symbol Active.
  Refresh	F5	See Refreshing Object Lists.
  Filter	F3	See Filtering Objects.
  Paste data	CTRL+V	See Pasting Objects.
  Set Drag And Drop Function	---	See Drag & Drop.

To list all functions available for a single symbol active

• Select a Symbol Active instance and open the context menu.

  The following functions are available:

  Function	Shortcut	Description
  Open	CTRL+O	See Modifying a Symbol Active.
  Display	CTRL+D	See Viewing a Symbol Active.
  Delete	DELETE	See Deleting a Symbol from a Symbol Table.
  Copy data	CTRL+C	See Copying Objects.
  Set Drag And Drop Function	---	See Drag & Drop.

Viewing a Symbol Active

To view a symbol active

• In the object workspace, select a Symbol Active instance and choose Display from the context menu, or press CTRL+D.

  A Display Symbol Active window similar to the Maintenance Symbol Active window opens.

  You can view all symbol definitions on the tabbed pages Main and Multiple Symbol Values.

  The fields and columns contained on the pages correspond to the field and columns of the Maintenance Symbol Active window. They are explained in Fields: Master and Active Symbols.

Adding a Symbol Active

To add a symbol active

1. In the object workspace, select a Symbol Active node.

2. Open the context menu and choose New, or press CTRL+N.

   A Create new Symbol Active window opens.

   The fields on the tabbed pages Main and Multiple Symbol Values of the window correspond to the fields of the Maintenance Symbol Active window. They are explained in Fields: Master and Active Symbols.

   Fill in the fields as required.

3. When you are finished, choose OK.

Modifying a Symbol Active

To modify a symbol active

1. In the object workspace, select a Symbol Active instance and choose Open from the context menu, or press CTRL+O.

   A Maintenance Symbol Active window similar to the example below opens:

   

2. Make your modifications. The fields on the tabbed pages Main and Multiple Symbol Values are explained in Fields: Master and Active Symbols.

3. When you are finished, choose OK.

   The symbol active is modified and saved.

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. In a Symbol Master or Symbol Active window, open the tabbed page Multiple Symbol Values.

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

   

   All values currently defined for the selected symbol are listed in a table. The table is empty if no values exist.

2. You can add a new value in an empty table row at the end of the table. If you want to insert an empty row, select the row above which you want to place it and choose Insert.

   Note:
   Incorrect value definitions (wrong format/length) or values that are not within a specified value range appear in red. For valid input values, see the description of the Value field and the Value Check page in the section Fields: Master and Active Symbols.

   If you want to delete an entry, select the appropriate row and choose Delete.

This section covers the following topics:

• Symbol Replacement

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 the Value Check page of a Symbol Master window.

2. Select the Range check button (default is None for no check) and enter a start number in the Value from field and an end number in the Value to field as shown in the following example of a Value Check page:

   

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

3. Choose OK to save your entries.

   You can deactivate the check by selecting the None button.

4. If you open the Multiple Symbol Values page and add a new value that is not within the specified range (here: 1 to 30) the new (incorrect) value (here: 33) appears in red:

   

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. Make sure that the Use symbol as option is selected in the respective node definition.

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. Open the Value Check page of a Symbol Master window.

2. Select the User exit button (default is None for no check) and enter the name of a library and a user exit in the fields Library and User exit, respectively. The input fields are described in Fields: Master and Active Symbols.

   Choose Edit if you want to modify the source of the user exit. Remember that you need to recatalog (STOW command) the source after modification.

3. Choose OK to save your entries.

4. Select the None button if you can deactivate the user exit.

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 master

1. In the object workspace, select a Symbol Master instance.

   Choose Delete from the context menu, or press DELETE.

   Or:
   In a Maintenance Symbol Table Master window, select the symbol you want to delete and choose Delete.

   A confirmation window opens.

2. Choose Yes to confirm the deletion or No to cancel the action.

To delete a symbol active

1. In the object workspace, select a Symbol Active instance.

   Choose Delete from the context menu, or press DELETE.

   Or:
   In a Maintenance Symbol Table Active window, select the symbol you want to delete and choose Delete.

   A confirmation window opens.

2. Choose Yes to confirm the deletion or No to cancel the action.