Adding and Maintaining Symbol Tables

This document covers the following topics:

• Listing Master Symbol Tables

• Versioning of Symbol Tables

• Copying Master Symbol Tables

• Adding a Symbol Table Master

• Displaying and Modifying a Master or Active Symbol Table

• Maintaining the Usage of Symbol Table Versions

• Deleting a Master Symbol Table

Listing Master Symbol Tables

To list all master symbol tables of an owner

• Select the Symbol Tables option from the Main Menu and press ENTER.

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

  01.12.15 ***** Entire Operations ***** 17:58:53 Owner EXAMPLE Main Menu User ID SAG --- +------------------------------------------------------------------+ ----- | | | Master Symbol Tables | | | 1 | Cmd Owner Symbol Table | 2 | EXAMPLE___ *_________ | 3 | _ EXAMPLE ADMIN | 4 | _ EXAMPLE EX-ST-COMN | 5 | _ EXAMPLE EX-VSE-1 | 6 | _ EXAMPLE EXA | 7 | _ EXAMPLE EXA-SYMBOL | 8 | _ EXAMPLE EXAM-ST1 | 9 | _ EXAMPLE EX321-ST1 | 10 | _ EXAMPLE E20-ST | 11 | _ EXAMPLE E20-ST-VSE | | _ EXAMPLE E29-ST | | C Copy D Delete L List Symbols | | U Version Usage W Where used | Com | Enter-PF1--PF2--PF3-----PF5-----PF7--PF8-----PF12- | | Help Add End Save Up Down Menu | +------------------------------------------------------------------+ Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help End Owner Mail

  This window lists master symbol tables already defined to Entire Operations. You see only the symbol tables that belong to your owner. If no master symbol tables have been defined for your owner, the list is empty. The columns are further explained in Columns: Master Symbol Tables.

  The commands are explained in Line Commands: Master Symbol Tables and Special PF Keys: Master Symbol Tables.

This section covers the following:

• Columns: Master Symbol Tables

• Line Commands: Master Symbol Tables

• Special PF Keys: Master Symbol Tables

Columns: Master Symbol Tables

The columns contained in the Master Symbol Tables window are described in the following table.

Line Commands: Master Symbol Tables

Use the following line commands to perform the described functions on any symbol table listed in the Master Symbol Tables window:

Special PF Keys: Master Symbol Tables

The Master Symbol Tables window provides the following special PF key:

The following sections describe the functions you can perform on master symbol tables using available line commands and PF keys.

Versioning of Symbol Tables

This section describes how to maintain and use different versions of symbol tables.

• Version Names

• Version Names Exit

• Reserved Version Names for Symbol Tables

• Creating Symbol Table Versions by Copying Symbol Tables

• Copying Single Symbols

• Deleting Symbol Table Versions

• Deleting Symbol Table Versions or single Symbols via API

• Using Symbol Table Versions for Schedule Activation

• Definition of Symbol Table Versions

• Active Symbol Tables

• Symbol Prompting

• Search Order for Symbols

• Symbol Tables at System and Owner Level

• Logging

• Cross-References (XREF)

• Reporting

• Import/Export

• Exit Functionality (Symbol Table)

• Maximum Number of Versions per Symbol Table

Version Names

The following applies when creating version names:

• The name can contain up to 10 alphanumeric characters and uppercase or lowercase letters.

• Space characters and the following special characters are not allowed:

  ?<>*‚()_

• In general, do not use special characters and umlauts to avoid problems when porting an Entire Operations environment to another platform.

• Do not use a reserved version name (see the following section).

Version Names Exit

With the usage of a global version names exit you can force a user-specific version name syntax. For detailed information, see Global Exit for Version Names in the Administration documentation.

Reserved Version Names for Symbol Tables

blank value; in selections and in the log also: (unnamed)

Is used for an unnamed version.

This is the only network version that exists after migration from an earlier Entire Operations version that does not support network versioning.

In parameter listings (e.g., for reporting) you can use also a hyphen (-).

(current)

Will be replaced by the version that is set in the activated time schedule. (current) can be used in version references.

(nv)

Will be replaced by the network version of the active network. If only an unnamed network version exists, then this symbol table will be referred to this.

If a symbol table version with the same name is not existent in the network version, then an error message will be sent and the request aborted.

(svn)

The symbol table version will be replaced thru the active network. (svn) can be used in referenced versions of a slaved network.

Example of use:

• Job definition

(svj)

The symbol table version will be replaced thru the active job. (svj) can be used in referenced versions of a slaved job.

Examples of use:

• Requested prerequisite dependent on the symbol value,

• Requested prerequisite dependent on multiple-value symbols,

• End-of-Job action: set symbol.

Creating Symbol Table Versions by Copying Symbol Tables

You can copy symbol tables to add a new version for an existing symbol table. This is a common way to build new symbol table versions.

See also Copying Master Symbol Tables.

Copying Single Symbols

Symbols in any version can copied out of the originating symbol table.

Deleting Symbol Table Versions

• If multiple versions of a symbol table exist, then one must select one to be deleted.

• A symbol table version cannot be deleted if listed in an activated time schedule as a standard version. A defined date in the past is not relevant.

Deleting Symbol Table Versions or single Symbols via API

By using the API NOPUSY7N you can delete single symbol table versions and symbols.

Using Symbol Table Versions for Schedule Activation

To maintain version usage in symbol table administration, use the functions described in Maintaining the Usage of Symbol Table Versions.

Definition of Symbol Table Versions

Symbol table versions can be defined in the following:

• Network versions definition,

• Job definition.

Active Symbol Tables

• The activation of symbol tables is a component of network and job activations.

• A symbol table can only be activated in a clearly identified version. The identification of the requested symbol table version is part of the activation process.

• Active symbol tables loose there version nomenclature (current) or (nv). They are detached during activation.

• Active symbol tables can only have the version nomenclature (none) or a defined version name.

• If a requested symbol table version is missing, or the version cannot be defined, then the activation process will be aborted with an error message.

Symbol Prompting

Before symbol prompting (during manual activation and before executing the symbol prompting exit in the Monitor), the symbol table versions to be used will be clearly determined. See also Symbol Prompting during Network or Job Activation.

If at least one symbol table version cannot be identified, the activation process will be aborted with an error message.

Search Order for Symbols

The order in which symbols are searched for in the symbol tables defined in your environment depends on the hierarchy levels at which the symbol tables defined in you environment can be accessed: see Symbol Table Types and Symbol Search Order.

Symbol Tables at System and Owner Level

Global symbol tables are not version-controlled.

The symbol tables are:

SYSDBA / A
owner / A

Logging

Logging of symbol actions include the version of the table where the symbol was loaded from.

The generated comments in the Entire Operations JCL header contain the symbol table version of all used symbols.

Cross-References (XREF)

Symbol table versions will be considered.

Reporting

Symbol table versions will be considered.

Import/Export

Symbol table versions will be considered.

Exit Functionality (Symbol Table)

Entire Operations provides user exits and APIs that are related to symbols and support network versioning, for example, API NOPUSY7N.

Maximum Number of Versions per Symbol Table

The maximum number of symbol table versions can be limited system wide as described in Default Setting (3) in the Administration documentation.

Copying Master Symbol Tables

You can copy a network definition to create a new network or another version for an existing network.

You can copy a symbol table to create a new symbol table or another version for an existing symbol table.

To copy a master symbol table

1. In the Master Symbol Tables window, type C in the line command input field next to the symbol table you want to copy. Press ENTER.

   A window similar to the example below opens:

   +-------------------------------------------------------------+ | | | Symbol Table Master Definition Copy | | | | From To | | Owner ==> SAGTEST___ Owner ==> SAGTEST | | Table ==> EXA-SYMBOL Table ==> EXA-SYMBOL | | Version ==> Version ==> __________ | | Alt. File ==> N (Y/N) | | | | PF3 End | +-------------------------------------------------------------+

   The From section contains read-only fields with the name of the owner, symbol table and symbol table version (if applicable) selected for copying.

   The To section contains modifiable target fields which are preset to the name of the owner, symbol table and version (if applicable) of the selected symbol table.

2. In the To fields, enter the name of the owner, symbol table and symbol table version (if required) to be used for the new symbol table.

   To open a selection window for owners or symbol tables, use an asterisk (*) as a wildcard.

   Notes:

   • You can only copy a symbol table to another owner if you are authorized to access networks belonging to that owner.

   • The current owner is used as the target symbol table owner. If necessary, use the direct command SET OWNER (see SET in the Direct Commands documentation) to change the current owner before a symbol table copy action.

   • You can copy a symbol table to an existing table and merge the two tables.

3. Press ENTER to copy the table to a new table or to combine it with an existing table.

   • If you have simply copied to a new table, this new table is now listed in the Master Symbol Tables window.

   • If you have combined two tables, this is performed in the following manner:

     • All symbols and their values are copied successively from the source table to the target table.

     • If an identical symbol with identical value(s) exists in both the source and the target table, then this symbol is not copied.

     • However, if the values of this identical symbol differ, the following window opens:

       +---------------------------------------------------------------------------+ | | | Symbol Table Master Definition Copy | | Identical Symbol detected - Please mark the desired Value | | M Owner SymTab Symbol modified by | | Copy from: | | SAGTEST EXA-SYMBOL MULT-01 IMPORT 18-02-08 10:39 | | Version (unnamed) | | Exit Library | | _ Value *** 5 multiple values *** Multiple Y | | Copy to: | | SAGTEST EXA-SYM2 MULT-01 SAG 18-05-17 17:09 | | Version (unnamed) | | Exit Library | | _ Value *** 2 multiple values *** Multiple Y | | | | PF3 End | +---------------------------------------------------------------------------+

       The input field and columns are explained in Fields and Columns: Different Symbol Values.

       In the above example, the value of the symbol MULT-01 in the source table EXA-SYMBOL is different from the value in the target table EXA-SYM2.

4. Use any character to mark the value to be retained in the target table after copying.

   In the example above:

   • If you mark Value *** 5 multiple values ***, the value of MULT-01 in EXA-SYM2 will be replaced by this value.

   • If you mark Value *** 2 multiple values ***, the value of MULT-01 in EXA-SYM2 will be retained.

     If you keep different values in source and target symbol tables, you will again be prompted to confirm the values the next time you copy these tables.

     Note:
     Every time a symbol value in the target table is overwritten by the pertinent value in the source table, a corresponding message is written to the log. When the whole copying process has been completed, a message is also written to the log.

5. Press ENTER when you are finished.

This section covers the following topic:

Fields and Columns: Different Symbol Values

Adding a Symbol Table Master

You can add a symbol table master by either copying an existing table (see Copying Master Symbol Tables) or creating a new symbol table with PF5 (Add). This requires that you define at least one symbol master along with the table.

This section provides instructions for using PF5 (Add).

To add a master symbol table

1. Choose PF2 (Add) in the Master Symbol Tables window.

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

   +---------------------------------------------------------------+ 14:50:57 | | . SV98 | Master Symbol Addition | n | | ------------ | Symbol Table EXA-SYMBOL Owner EXAMPLE | | Version SV98______ Network | | Run | .08.96 13:15 | Symbol Name DARMSTADT-LILIES________________________ | .09.96 09:36 | Format A | .09.96 09:39 | Value golden-goal_____________________________ | .12.15 18:38 | ________________________________________ | .09.96 09:38 | ________________________________________ | | Be careful with insertions or deletions. | | The lines will be concatenated to one symbol value. | | | | Prompting E Update Mode _ | | Prompt Text Different by Tradition__________________ | | ________________________________________ | | ________________________________________ | | ________________________________________ | ************ | ________________________________________ | | Enter-PF1---PF2---PF3-----PF5----PF8----PF9---PF10---PF11-- | | Help Add End Save RgChk Mult Copy Exit | +---------------------------------------------------------------+ Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Add End Copy Save Up Down Print

2. Enter the name of a new master symbol table and define the first symbol for it. The input fields are described in Fields: Master and Active Symbols. The special PF keys available are explained in Special PF Keys: Master Symbol Addition.

3. If you wish to add more symbols to the new table, choose PF2 (Add) from the Master Symbol Addition window. This saves the first definition and clears the window.

   You can now add another symbol. You can add any number of symbols to a master symbol table.

4. Choose PF5 (Save) to save the new master symbol table.

5. Choose PF3 (End) to close the window and return to the Master Symbol Tables window. The new master symbol table appears in the list.

   You can add any number of master symbol tables for your owner.

This section covers the following topics:

• Special PF Keys: Master Symbol Addition

• Fields: Master and Active Symbols

• Example

Special PF Keys: Master Symbol Addition

You can perform the following functions from the Master Symbol Addition window using these PF keys:

Fields: Master and Active Symbols

The fields in the Master Symbol or Active Symbol window and subordinate windows are described in the following table.

The fields are either write-protected or available for input depending on whether you view or modify the symbols. The table indicates when a field does not apply to active symbols.

Example

The following example illustrates the use of the symbol FILE-1 in the master symbol table A-1:

+---------------------------------------------------------------+
|                                                               |
|                    Master Symbol Modification                 |
|                                                               |
|  Symbol Table A-1_______                   Owner SAG          |
|       Version v12.44____                 Network              |
|                                              Run              |
|  Symbol  Name FILE-1__________________________________        |
|        Format A                                               |
|         Value NOP.DEMO.SRCE___________________________        |
|               ________________________________________        |
|               ________________________________________        |
|         Be careful with insertions or deletions.              |
|         The lines will be concatenated to one symbol value.   |
|                                                               |
|     Prompting E                          Update Mode _        |
|   Prompt Text ________________________________________        |
|               ________________________________________        |
|               ________________________________________        |
|               ________________________________________        |
|               ________________________________________        |
| Enter-PF1---PF2---PF3-----PF5----PF8----PF9---PF10---PF11--   |
|       Help  Add   End     Save   RgChk  Mult  Copy   Exit     |
+---------------------------------------------------------------+

For each occurrence of the symbol FILE-1 in the JCL of the job for which symbol table A-1 with version v12.44 is specified, the value NOP.DEMO.SRCE is substituted. For example, the JCL line:

//XYZ  DD DSN=@FILE-1,DISP=SHR

as defined in the original JCL, becomes:

//XYZ  DD DSN=NOP.DEMO.SRCE,DISP=SHR

at job activation time.

The user can modify the resulting JCL for a single job run as described in Editing Active JCL in the section Maintaining Active Jobs and Networks.

When the job network which uses this symbol table is activated manually, the user is prompted for this symbol. The text in the Prompt Text field is displayed during symbol prompting to help the user specify the correct value. The user can leave the specified value or modify it for the network run.

Displaying and Modifying a Master or Active Symbol Table

Modifying a master symbol table or an active symbol table consists of adding, modifying or deleting symbols and their current values.

To display or modify a master or an active symbol table

1. In the Master Symbol Table window, type L (List Symbols) in the Cmd input field next to the required symbol table, and press ENTER.

   Or:
   In a Job Definition (Master) or Job Definition (active) window, choose PF7 (Symb).

   A Usable Symbol Tables window opens.

   In the Cmd column, type L next to the required symbol table, and press ENTER.

2. A Master Symbol Table or Active Symbol Table screen appears for the selected symbol table:

   28.02.19 ***** Entire Operations ***** 13:35:39 Owner EXAMPLE Master Symbol Table EXAMPLE EXAM-ST1 Ver. (unnamed) Network B60-FLOW Run ------------------------------------------------------------------------------ C Symbol F P Value modified by *------------------- _ CLASS A E G SAG 03.11.11 16:49 _ JOBLIB A E NOP.EXAMPLE.LOAD SAG 03.11.11 16:49 _ MSGCLASS A E X SAG 03.11.11 16:49 _ PARM-1 A E test SAG 03.11.11 16:49 _ STEPLIB A E NOP.EXAMPLE.LOAD SAG 03.11.11 16:49 ******************************* 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 screen lists the symbols defined for the table by name, format, prompt value and current symbol value. Information is provided on the right concerning the user and date and time when the symbol was last modified.

   You can add, modify and delete a symbol from the symbol table.

This section covers the following topics:

• Columns: Symbol Table Master

• Special PF Keys: Symbol Table Master

Columns: Symbol Table Master

The columns on the Master Symbol Table screen are explained in the following table:

Special PF Keys: Symbol Table Master

The Master Symbol Table screen provides the following special PF key:

Maintaining the Usage of Symbol Table Versions

You can determine a period (from/to date range) during which a particular symbol table version is used as the current symbol table for all scheduled job activations.

The Version Usage function is used to define the maintenance of date ranges, in which symbol table versions are to be used for scheduled activations.

This section covers the following topics:

• Listing, Defining and Deleting Version Usage

• Fields and Columns: Version Usage Definition

• Commands: Version Usage Definition

Listing, Defining and Deleting Version Usage

This section provides instructions for listing, defining and deleting version usage definitions for symbol table versions.

To list the version usage defined for a symbol table

• In the Master Symbol Tables window, enter the line command U (Version Usage) next to required symbol table, and press ENTER.

  A Symbol Table Version Usage screen similar to the example below appears:

  18.12.13 ***** Entire Operations ***** 10:45:16 Symbol Table Version Usage Owner SN Symbol Table A-1 ------------------------------------------------------------------------------ Cmd from to Version Description -------- -------- *--------- _ 18.12.13 31.12.13 v10.05 for the rest of 2013 _ 01.01.14 >>>>>>>> v12.44 starting 2014 ******************************* Bottom of Data ******************************* D Delete M Modify Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Add End Up Down Left Right

  The fields and columns available on the screen are explained in Fields and Columns: Version Usage Definition. The commands available are explained in Commands: Version Usage Definition.

To add or modify a version usage definition

1. On the Symbol Table Version Usage screen, choose PF2 (Add) to create a definition.

   Or:
   On the Symbol Table Version Usage screen, enter the line command M next to the version you want to modify, and press ENTER.

   The input fields that appear are shown in the following example:

   18.12.13 ***** Entire Operations ***** 10:48:42 Symbol Table Version Usage Owner SN Symbol Table A-1 ------------------------------------------------------------------------------ Symbol Table Version ==> v12.44____ is to be used as current Version (current) from ==> 01.01.14 (empty: unlimited) to ==> ________ (empty: unlimited) Version Usage Description starting 2014_________________________________________________________ Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help End Save

2. Enter the required values. The fields are explained in Fields and Columns: Version Usage Definition.

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

Fields and Columns: Version Usage Definition

Commands: Version Usage Definition

The following line commands and special PF keys are available on the Symbol Table Version Usage screen:

Deleting a Master Symbol Table

Restrictions:

• You cannot delete a master symbol table that is still used by one or more jobs. In this case, the error message EOR1859 - Symbol Table ... used in Definitions occurs. You can only delete the symbol table if you either specify another symbol table for these jobs or delete them. Proceed as described in Listing Jobs and Networks that Use a Symbol Table Master to find the jobs that use the symbol table.

• You cannot delete a master symbol table with a symbol table version that is still defined in the version usage of the symbol table. In this case, the error message EOR2691 - Version ... - current usage found occurs. You then need to delete the usage defined for the version as described in Maintaining the Usage of Symbol Table Versions.

To delete a master symbol table

1. In the Master Symbol Tables window, type D in the line command input field next to the symbol table you want to delete. Press ENTER.

   If more than one version exists for the symbol table, a Symbol Table Version Selection window similar to the example below opens:

   +-------------------------------------------------------------------+ | | | Symbol Table Version Selection | | Owner EXAMPLE Symbol Table EXAM-TABLE | | Version Usage | | _ T-V2 01.01.16 - >>>>>>>> - current at 04.05.16 | | _ T-V1 01.04.15 - 31.12.15 | | | | | | | | | | | | | | | | | | | | | | ** Bottom ** | | ----------PF3-----------PF7---PF8----------------------------- | | End Up Down | +-------------------------------------------------------------------+

2. Select each version with any character and press ENTER.

   If the symbol table (and individual symbol table version) is no longer used or defined elsewhere, a window similar to the example below opens:

   +------------------------------------------------------------------+ | | | Master Symbol Tables | | | | Cmd Owner Symbol Table | | EXAMPLE___ EXA*______ | | _ EXAMPLE EXA | | +-------------------------------------------------------------+ | | | | | Please confirm | | | the Deletion of EXAM-TABLE | | | by entering EXAM-TABLE | | | ==> ______________________________ | | | PF3 End | | +-------------------------------------------------------------+ | | | C Copy D Delete L List Symbols | | U Version Usage W Where used | | Enter-PF1--PF2--PF3-----PF5-----PF7--PF8-----PF12- | | Help Add End Save Up Down Menu | +------------------------------------------------------------------+

3. Enter the symbol table name and press ENTER to delete the table.