Performing Tasks with SMA

This section describes the major tasks which can be performed using SMA.

Note:
In this section, the term "tape" represents any installation media (e.g. tape and CD-ROM) supported by Software AG. The information provided here applies to the use of any of these media.


Defining the User Environment

Before using SMA to generate JCL, it is necessary to define various parameters related to local conventions and requirements for the user environment.

This will enable SMA to generate JCL which can be executed with minimal changes. The information provided can then be used for all future JCL generation.

You can adapt SMA to your site's specific requirements by performing the following steps:

Note:
SMA internally uses the notations OS/MVS, VSE/SP and BS2000 for designating the operating system and default environment. These notations directly correspond to the operating systems z/OS, VSE/ESA or z/VSE, and BS2000/OSD, respectively.

Step 1: Specify SMA Profile Parameters

Enter the Administration function from the SMA Main Menu and select SMA Profile.

Make any necessary changes to the default values provided. The parameters which can be specified in the SMA Profile can apply to this session only, or they can be stored permanently.

Step 2: Specify Global Parameters

From the Administration function, select Global Parameters. Enter the required values.

Step 3: Specify Parameters for Default Environment

You will probably need to change certain values for the default environment, especially the parameters belonging to the parameter groups BASIC and LIBGRP, before creating your working environments as copies of the default environment. The name of the default environment corresponds to the name of the operating system in use (OS/MVS, VSE/SP, BS2000).

Parameter Modification

To modify the parameter values, proceed as follows:

  1. Enter the Environment function from the SMA Main Menu and select your default environment using the line command MG (Modify Parameter by Group).

  2. In the list of parameter groups, select a parameter group by marking it with an "X".

  3. Enter values for these parameters in the column labeled New Value. SMA will store these new values temporarily when you press Enter.

Note:
The Adabas transaction time limit may be exceeded during the modification of large numbers of parameters. It is recommended to save your modifications frequently using the direct command SAVE.

Step 4: Modify JCL Skeletons for Default Environment

You may modify the JCL skeletons either in the default environment or in your working environment. Changes in the default environment apply to all other environments, and should therefore be made first.

To modify JCL skeletons in the default environment, proceed as follows:

  1. Enter the Environment function from the SMA Main Menu and select your default environment using the line command MS (Maintain Skeletons).

  2. Select the skeleton using line command MO (edit) or DI (display).

Note:
The lines of a JCL skeleton may contain conditions. These conditions are used by the JCL Generator to determine whether or not the line is to be included in the generated JCL. You can modify these conditions by pressing PF11 in the Edit JCL Skeleton screen. After making any required condition modifications, press PF10 to continue editing the skeleton.

Caution:
Do not delete JCL lines which contain conditions. Such lines are part of the network of SMA's installation information.

For more information on using and modifying JCL skeletons, refer to the section JCL Skeletons.

Step 5: Commit Changes for Default Environment

SMA stores most information in two versions: installed and to be installed. This status is used by the JCL Generator to determine which changes to the environment specification are new and are to be installed. After successful execution of all generated jobs, the products are set to status installed, and the new parameter values become the installed values.

The changes made so far are only valid in the default environment, which is not meant for JCL generation, but rather to supply the other environments with default values. Therefore, you have to specify to SMA explicitly that the values entered so far are installed.

To do this, access the Environment function from the SMA Main Menu and issue the line command SE (Set Installed) for your default environment.

Installing Software AG Products with SMA

This section describes how to use SMA to install a product contained on the installation medium (e.g., tape) received from Software AG.

Caution:
You cannot use SMA to install a subproduct of Natural without having first installed Natural itself.

If you have already installed Adabas and Natural in one or more databases, it is recommended to start using SMA with the installation of the next Natural version.

Step 1: Load the SMA Tables to Disk

Whenever you receive an installation tape from Software AG, you must make this medium known to SMA. A product installation tape can be distinguished from other Software AG tapes by:

  • The volume serial number: Tnnnnn, where nnnnn is a 5-digit number.

  • The name of the first data set on the tape is SMT111.TABS.

Before proceeding, check to ensure that the parameter LIB-GROUP in your default environment has been modified according to your requirements.

Caution:
Setting the value of the LIB-GROUP parameter must be done carefully. This parameter can be changed like all other parameters after JCL generation, but in this case, you will have to delete all the then obsolete entries for library copies by using the SMA Tape Handling function.

To make the tape known to SMA, execute the command LOAD. This command requires the first data set on tape SMT111.TABS to be assigned to Natural Workfile 1. Therefore, you should usually start this process in batch mode.

The installation tape's description will then be loaded into your SMA system file. This description contains data for SMA's JCL Generator as well as descriptive text. See the member TABLOAD in the SMA source library for an example job.

You should read the text describing the tape and, based on this information, decide how to proceed. You can find this information in two ways:

  • Select the tape report for this tape from the Reports menu.

  • Enter the Tapes function from the SMA Main Menu, and select one of the functions available for the new tape:

    • Show the list of products (line command PR) on this tape.

    • Show the list of data sets (line command DA) on this tape.

Step 2: Set the LIB-GROUP Parameter

During JCL generation, SMA must be able to locate all required installation data sets. Therefore, all copy steps for Software AG's installation data sets must be controlled by SMA.

The JCL Generator uses the descriptions of the data sets to produce copy steps to copy all libraries from the installation tape to disk which have not yet been copied.

SMA makes some assumptions about copying based on the parameter LIB-GROUP:

  • Data set names (DSNs) for data sets on disk are created by concatenating the default DSN prefix, which is stored in the parameter LIB-GROUP, with a period (.) and the DSN as it is stored on tape. For example, if the value of the parameter LIB-GROUP is SAGLIB, the name of the Natural load library will be SAGLIB.NAT&&&.LOAD. If the last character of the LIB-GROUP parameter value is an asterisk (*), the period and the asterisk will be omitted in the data set name on disk.

  • The name and device type of the disk are taken directly from the parameters LIB-GROUP-VOLSER and LIB-GROUP-UNIT, respectively.

Creation of Library Copies

The first phase of the JCL Generator determines which libraries have to be copied. A library is copied from the delivery library if:

  • It does not exist according to the current value of the LIB-GROUP parameter.

  • It belongs to a product which is marked as installed or to be installed in this environment.

At this point, the JCL Generator enters the default data set names, etc., as described above, into the list of data set names. These entries are marked as to be copied.

Controlled Copying

As described above, the creation of a copy entry is normally done by the JCL Generator. If you wish to control this copy process, proceed as described below.

The SMA Tapes function can be used to control the copying:

  1. Enter the line command DA in the tape selection list for the tape.

  2. Enter the line command MO for the data set(s) you want to copy from tape to disk.

  3. Modify the data set parameters that describe the storage on disk.

  4. Enter the line command MA for this data set. The data set will be marked as to be copied, and the required JCL will be generated during the next JCL generation.

This process is useful if you want to copy several data sets (not just the libraries) from tape to disk. If you have sufficient disk space, it is convenient to have all installation data sets available on disk.

Experienced users can also use these facilities to direct SMA to use existing libraries. Let the JCL Generator decide which copy entries are needed according to your LIB-GROUP parameters, then enter the SMA Tapes line command DA for the specified tape/CD, and then change the Data Set Name on the disk for the desired data set with line command MO.

Step 3: Library Preparation

Depending on the operating system environment, certain libraries are required as described below.

z/OS Environment

The Software AG product library must have been created during the installation of SMA (see the section Installing SMA).

Two work libraries are required for each environment you are using in SMA:

  • A load library to receive the results of the linkage editor steps.

  • A source library for the generated source members (for example, the Natural parameter modules).

Ensure that these libraries are allocated on your system.

In the next step, you must enter the names of these libraries as the parameters DSN-SMALOAD and DSN-SMASRCE.

z/VSE Environment

The Software AG product library must have been created during the installation of SMA (see the section Installing SMA).

Define one sublibrary per environment in the Software AG product library. The names of these sublibraries must be specified in parameter USRLIB in the next step. Most of the assembly and link steps of the generated jobs will use these sublibraries as target libraries.

BS2000/OSD Environment

No additional libraries are required. For more information, see LMS Libraries Used by SMA.

Step 4: Define Your Installation Environment

The main step in product installation is the description/modification of your environment.

Proceed as follows:

  1. If you want to install in a new environment, copy or clone an existing environment to create a new environment, and enter up to four lines of descriptive text.

  2. Select the new environment from the selection list using the line command MO.

  3. Select Install Products, and use the line command IN to mark the products you want to install. The selected products will receive the status to be installed. You need not install all products at once; it is recommended to install the basic products first, and then install other products later. SMA will check possible prerequisites or conflicts between products marked as installed or to be installed.

  4. Modify the parameters to suit your requirements.

Notes:

  1. When a new product installation tape is loaded, a report is provided which shows which new parameters have been loaded. This can be used to prepare the installation of a new product.
  2. Before installing any product you should inspect parameters in group OPTION. These parameters control how a product is installed.
  3. A typical OPTION parameter is xxx-FIRST-INSTALL. This parameter must be set to Y if the product xxx is being installed for the first time. In this case, more installation steps may be needed.
  4. The list of OPTION parameters will expand as new products are loaded into SMA. Thus, it is not possible here to document a complete list. Make sure you review the parameters currently available.

Step 5: Generate JCL

After you have marked the products to be installed and made all necessary install parameter modifications, you can use SMA to generate the JCL. This can be done in online dialog mode or in batch mode.

JCL Generation in Dialog Mode

Use the direct command GENERATE <environment> or the line command JC for the selected environment from the Environment Maintenance menu to start JCL generation.

The JCL Generator will produce installation steps not only for the products marked as to be installed, but also for all those steps containing a changed parameter.

Note:
The SMA analysis for this generation process can require significant time and resources.

The results of this analysis are provided as the Installation Guide. You should print out this guide and use it as a checklist for successful execution of all jobs and steps.

The JCL Generator will store the generated jobs in the SMA system file. You can then review the jobs and modify them if necessary.

Note:
For BS2000/OSD, when you enter the GENERATE command in dialog mode, a job will be submitted to perform the JCL generation in batch mode after all consistency checks have been completed successfully.

Note:
For z/OS and z/VSE, the line command JB can be used to perform the consistency check and then submit the job to perform the JCL generation in batch mode. Natural Workfile 2 contains the generated JCL and control records for the corresponding library utility (IEBUPDTE, LIBR). This is useful when the generated JCL is to be used outside of SMA.

Description of Generated Jobs

Four groups of jobs are generated (xxx represents a three-digit number):

  • Txxx: Tape copy jobs. These jobs copy the libraries and the marked data sets. One job is generated per tape. xxx represents the last 3 digits of the volume serial number.

  • Pxxx: Preparatory jobs. These jobs perform preparatory tasks for the installation.

  • Ixxx: Installation jobs. These jobs perform the installation. Job I999 sets the status of products and parameters from to be installed to installed.

  • All other jobs are example jobs which are not part of the product installation.

Generated Steps

SMA generates the steps which are necessary based on the following conditions:

  • The step belongs to the installation sequence of a product which is to be installed.

  • The step contains lines which are dependent on a product which is to be installed. Example: Many subproducts of Natural affect the Natural parameter module. Thus, this parameter module will be generated whenever such a subproduct is installed.

  • The step contains parameters which have a new value. In some cases, too many steps will be generated (for example, when changing the name of the batch Natural nucleus or the name of the assembler), because SMA cannot decide whether or not changing a parameter requires the re-execution of the corresponding step. It may therefore be necessary to delete unnecessary steps prior to submitting the JCL for execution.

  • The step is a logical successor of a step already selected. Example: A new parameter module must be assembled; afterwards, Natural must be linked.

  • The step is a logical successor of a Zap or source change.

JCL Generated for z/OS and z/VSE

z/OS and z/VSE users may invoke the SMA JCL Generator either in batch mode or within the SMA dialog. Both methods have their specific advantages:

  • JCL generation in dialog mode is the method for which SMA was primarily designed. Jobs are created according to the input provided by the SMA user as submitted from within the SMA dialog. The SMA user then usually deletes the generated JCL after successful execution.

  • The SMA user may save generated jobs within SMA, and may unload stored jobs using batch mode execution of the SMA UNLOAD JOBS command.

  • When invoked in batch mode, the JCL Generator writes the JCL generated into its system file as well as to a work file. The work file contains separators in IEBUPDTE or LIBR format between the different jobs to allow for loading this output into libraries. See the job JCLGEN in the SMAnnn.SRCE library for an example.

  • The generated jobs are created using the same set of job names with each JCL generation. SMA users who wish to keep generated jobs must use a JCL library and a naming convention for their own jobs.

JCL Generated for BS2000/OSD

See the section Using SMA under BS2000/OSD, JCL Generation.

Step 6: Review and Submit the Generated Jobs

The generated JCL can now be submitted to the operating system for execution as described below.

Submitting Jobs in z/OS and z/VSE Environments

  1. Print job P060. Follow the instructions which are contained in this job.

  2. Review and modify the generated jobs as required. If the generated jobs do not correspond to your requirements, you should consider changing the appropriate installation parameters or JCL skeletons for the environment. It is also possible to modify the generated jobs. This should, however, be avoided since these corrections must be repeated after each generation, whereas changes made to the environment will be valid for all future JCL generations. If you are sure that SMA generated too many steps, either delete them in the generated jobs, or perform the following procedure which ensures that only those steps are generated which are dependent on the products marked as to be installed:

    • Enter the Environment function of SMA, enter line command SE.

    • Enter the line command MO, select Products Installed in Environment, and mark the products you want to install again.

    • Repeat the JCL generation (Step 5).

  3. Submit the generated jobs in the following sequence:

    • The Txxx jobs in any order, if any.

    • The Pxxx jobs in any order (except for the Readme job P060).

    • The Ixxx jobs in the order indicated by the job name.

    After execution of the jobs, check whether or not they have been completed without error.

  4. Print job I100. Follow the instructions which are contained in this job.

  5. If you wish, you can save the generated jobs. SMA assumes that once a job has been executed successfully, it will be deleted. The JCL Generator will prompt you to delete any jobs which might still exist for the current environment. If you want to keep generated jobs, use the line command CO on the Generated Job screen to copy the jobs. Then you can display the list of saved jobs using option Saved Jobs from the Administration Menu.

Submitting Jobs in BS2000/OSD Environment

See section Using SMA under BS2000/OSD, SMA Installation Jobs.

Maintaining Software AG Products with SMA

This section describes how to maintain Software AG products using SMA.

Install New Product in an Existing Environment

When you receive a product installation tape containing a new product from Software AG, proceed as follows:

  1. Make the new tape and the product known to SMA by executing the LOAD command for this tape.

  2. Invoke the Environment Maintenance function (E) from the SMA Main Menu.

  3. Select your test environment by marking it with the line command MO.

  4. Select Install Products.

  5. Mark the new product to be installed using line command IN.

  6. Return to the Environment Maintenance screen and enter the line command JC for your test environment to generate the JCL for the product installation.

You can then review and submit the generated JCL to the operating system to install the product.

Install New Version of a Product in an Existing Environment

A new version of a product is considered by SMA to be a new product. Therefore, the steps described in section Installing Software AG Products with SMA also apply when installing a new version of a product which is already installed in an environment:

  1. Perform Step 1: Load Installation Tape (batch job TABLOAD).

  2. Perform Step 2: Copy Data Sets from Tape to Disk.

  3. Skip Step 3: Library Preparation.

  4. Perform Step 4: Define Your Installation Environment:

    • Mark the new version (for example, NAT414) to be installed, and leave the older version (for example, NAT413) marked as installed.

      Note:
      When a new product version is set to status installed, the status of the older version will be reset to not installed automatically.

    • Adapt the parameters in group OPTION which pertain to this product.

  5. Perform Step 5: Generate JCL.

  6. Perform Step 6: Review and Submit the Generated Jobs:

    • In some cases, migration jobs will be required. For example, when data formats have been changed from one major version to the next. SMA recognizes this and generates migration steps based on the presence of the two versions of the product.

    • In some cases, it will be necessary to delete parts of a product installation before the installation steps of the new version can be executed. To avoid inadvertent loss of data, such operations are not generated by SMA.

      Example:

      When installing a new version of the product Con-nect, the load step for the Con-nect system file is also generated. This step does not run when a system file already exists. You must either delete this system file or omit the load step. The information required for tasks like this is contained in the product documentation.

Install Solutions (Corrections for IUPDs, INPLs, ERRNs, Load Libraries)

SMA can also be used to install solutions which may contain corrections to IUPD, INPL and ERRN objects which are stored in the Natural system file or object modules for the load libraries, which replace the modules in the actual load library. Because each Natural system file is controlled by an SMA user environment, it is necessary to install these corrections in the same manner as products within an SMA user environment.

Naming Conventions

Solutions are identified by a solution ID which has the following format:

pppvvvtnnn

Where:

ppp is the short name of the product.

vvv is the product version, system maintenance level, or release level of the product.

t is the solution type. Valid values are: B (SMA TABS), E (Natural Error Message), I (Natural IUPD), L (Executable Module), P (Service Pack), S (Natural Summary INPL Data Set).

nnn is a 3-byte solution number.

Examples: NAT414I001 ADA743L123

Note:
For a better overview, SMA displays solution lists only for products which are marked installed or to be installed in an environment. These solutions can be received from Software AG support or via Software AG's online support system (ServLine24: http://servline24.softwareag.com).

To install such a correction, perform the following steps:

  1. Make the new tape (or data set) with the correction known to SMA by executing the LOAD command for this tape.

  2. Invoke the Environments function from the SMA Main Menu.

  3. Select the target environment by entering the line command MO.

  4. Select Install Products/Solutions from the Modify window.

  5. Mark the correction for installation using the line command IN.

  6. Return to the Environment Selection list. Enter the line command JC to generate the necessary JCL to install the correction. Submit the generated job to the operating system.

Install Library Corrections

Corrections (Zaps) to product libraries are maintained and applied using a separate SMA function which can be invoked by selecting option Z from the SMA Main Menu.

Entering Corrections

There are various ways to enter a correction into SMA.

If one or several corrections are available as a sequential file, you can load them into SMA using the LOAD command. Use job TABLOAD as an example, assigning Natural Workfile 1 to the data set containing the corrections.

If one or several corrections are available as MS/DOS files on your PC (for example, via ServLine24: http://servline24.softwareag.com), you can load them into SMA using the LOAD command. The conventions documented above apply in this case as well. Since the LOAD command reads Natural Workfile 1, you must invoke Natural with Workfile 1 assigned to the PC, for example:

NAT4 WORK=(PC3,...),PC=ON

After loading the correction file, you should print report A or Z for a list of the corrections available.

Applying Corrections

SMA can be used to apply available corrections to the members of the installation libraries in the library groups by:

  • Using function Z from the SMA menu. The list of all library groups will be displayed.

  • Using line command ZA from the selection menu. Only the library group of the selected environment will be displayed.

A library group may be used in different environments. Thus, applying a correction to a library group may affect multiple environments.

Note:
SMA cannot be used to apply corrections to linked modules.

To apply/undo a correction, perform the following steps:

  1. Select option Z from the SMA Main Menu. Specify the library group for which this correction is to be applied/undone using the line command DI.

  2. In the list of corrections, mark the corresponding corrections with the line command AP or UN.

  3. Enter line command JC for your library group in the list of library groups to generate JCL for the correction application. During JCL generation, SMA evaluates which linked modules are affected by this correction. This information is displayed and kept internally by SMA. After JCL generation, the Generated Jobs screen indicating the list of jobs will be displayed.

  4. Submit the generated job(s) to apply/undo the correction(s). The last step of this job sets the status of the corresponding correction(s) to is applied or undone, respectively.

  5. Make the correction effective by re-linking all affected modules. This is done simply by invoking JCL Generation in the corresponding environments. SMA determines which executable modules have to be re-linked, and generates the appropriate JCL. Several reports providing information on corrections are available from the Reports menu (see Reports in section Menus and Line Commands) or using direct commands (see Reports in section Direct Commands).