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

• Predefined Symbols

• 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. Type L in the line command input field of the selected symbol on the Master Symbol Table screen. 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. Press PF3 (End) to return to the Master Symbol Table screen.

Adding a Symbol Master

To add a symbol to a symbol table

1. Press PF2 (Add) on the Master Symbol Table screen. 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. Press 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. Type C in the line command input field of the selected symbol on the Master Symbol Table screen. 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. Type M in the line command input field of the selected symbol on the Master Symbol Table screen. 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. Enter your modifications.

3. Press PF5 (Save) to save the modified 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.

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 window similar to the example below opens:

   Multiple Symbol Values Owner SN Network Symbol Table A-1 Run Version Version v12.44 Symbol MULT-01 ------------------------------ Values 1 to 13 ----------------------------- aaaaaaaaaaaaaa________________________________________________________________ bbbbbbbbbbb___________________________________________________________________ ccccccccccccccc_______________________________________________________________ ddddd_________________________________________________________________________ eeeeeeeee_____________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ Enter---PF1----PF2----PF3--------PF5--------PF7----PF8----PF9----------------- Help Insert End Save Up Down Delete

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.

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

• 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 similar to the example below opens:

  19.12.13 ***** Entire Operations ***** 10:12:03 Owner SN Master Symbol Table A-1 Version v12.44 +---------------------------------------------------------------+ ! ! ------------ ! Master Symbol Modification ! ! ! ! Symbol Table ===> A-1_______ Owner SN ! .05.13 15:25 ! +-----------------------------------------------+ ! .12.13 09:27 ! Symbo ! ! ! .12.13 09:35 ! ! Symbol: Numeric Range Check ! ! .12.13 10:12 ! ! ! __ ! .12.13 09:26 ! ! Owner ===> SN ! __ ! .03.12 15:03 ! Be car ! Symbol Table ===> A-1 ! ! .05.13 16:44 ! The 2 ! Version ===> v12.44 ! ! ! Pr ! Symbol ===> NUM-1 ! _ ! ! Prom ! ! __ ! ! ! Value from ===> 1_________ ! __ ! ! ! Value to ===> 999_______ ! __ ! ! ! ! __ ! ! ! ---PF1--PF3---------PF5---------PF9---- ! __ ! ************ ! Enter- ! Help End Save Delete ! -- ! ! +-----------------------------------------------+ ! F11--PF12--- +---------------------------------------------------------------+

  In the following example, a value was entered outside the specified value range. In this case, an error message appears and Entire Operations does not accept the invalid value. This also applies to user exits that perform symbol checks (see also User Exits for Validation Checks of Symbol Values).

  19.12.13 ***** Entire Operations ***** 10:12:03 Owner SN Master Symbol Table A-1 Version v12.44 +---------------------------------------------------------------+ ! EOR0160 - Range is 1 thru 999 ! ------------ ! Master Symbol Modification ! ! ! ! Symbol Table ===> A-1_______ Owner SN ! .05.13 15:25 ! Version ===> v12.44____ ! .12.13 09:27 ! Symbol Name ===> NUM-1_______________ Network ! .12.13 09:35 ! Format ===> N Run ! .12.13 10:12 ! Value ===> 1888.567890 ! .12.13 09:26 ! ________________________________________ ! .03.12 15:03 ! Be careful with insertions or deletions. ! .05.13 16:44 ! The 2 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 ! F11--PF12--- +---------------------------------------------------------------+

For valid input values, see the description of the field Value and the sub-windows Numeric Range Check and Multiple Symbol Values page in the section Fields: Master and Active Symbols.

Predefined Symbols

Entire Operations provides a large number of predefined symbols that are reserved for system variables or particular system tasks. We strongly recommend not to use any of these symbols for user-defined purposes.

Predefined Symbol Ranges

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

• Predefined Symbols for Command Line Parameters

• Predefined Symbols for Mainframe Platforms

• Predefined Symbols for FTP Jobs

• Table of Predefined Symbols

• Predefined Symbols for Multiple and Parallel Activations

• Predefined Symbols for Subnetworks and Recovery Jobs

Predefined Symbols for Command Line Parameters

Passing Command Line Parameters

If you want to pass command line parameters for a job, use the predefined 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 submitted, Entire Operations checks whether a symbol CMDLINE-job exists.

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

• 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 #!/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 Bournce 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 1000 bytes (including separating blanks).

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

Predefined 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.

Predefined 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.

Table of Predefined Symbols

The following symbols 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-C-MPA (A50) 
§ 1 REDEFINE P-C-MPA ... 
#GET-SYMBOL P-C-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

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:

   19.12.13 ***** Entire Operations ***** 10:19:58 Owner SN Master Symbol Table A-1 Version v12.44 +---------------------------------------------------------------+ ! +-------------------------------------------------------------------+ ! ! ! ! ! Definition of Symbol Check Exit ! ! Symbo ! ! ! ! Owner ===> SN ! ! Symbo ! Symbol Table ===> A-1 ! ! ! Version ===> v12.44 ! ! ! Symbol ===> FILE-1 ! ! ! ! ! Be car ! Library ===> ________ ! ! The 2 ! Exit ===> ________ ! ! Pr ! ! ! Prom ! ---PF1-----PF3---PF4---PF5---------PF9--------------------- ! ! ! Help End Edit Save Delete ! ! +-------------------------------------------------------------------+ ! ________________________________________ ! ! ________________________________________ ! ************ ! Enter-PF1---PF2---PF3-----PF5----PF8----PF9---PF10---PF11-- ! ! Help Add End Save RgChk Mult Copy Exit ! F11--PF12--- +---------------------------------------------------------------+

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 check, 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.