This document describes installation procedure for Natural ISPF under the operating system z/OS.

Warning: If you are migrating from a previous version of Natural ISPF, be sure to refer to the section Migrating from Previous Versions.

This document covers the following topics:

• Step 1: Prepare, Convert, Assemble, and Link the License File

• Step 2: Copying the Medium Contents to Disk

• Step 3: Loading System Programs and Error Messages

• Step 4: Loading Predict Data

• Step 5: Modifying the Online Natural Parameter Module

• Step 6: Modifying Natural VSAM Parameters

• Step 7: Assembling the Parameter Modules for the ESX Component

• Step 8: Linking the Gateway Modules for the ESX Component

• Step 9: Relinking Natural with Natural ISPF

• Step 10: Loading / Migrating the Natural ISPF Versions File

• Step 11: Loading the Natural ISPF Container File

• Step 12: Natural Security Definitions

• Step 13: Required Interfaces to Other Software AG Products

• Step 14: Optional Interfaces to Software AG Products

• Step 15: CA Librarian Interface - z/OS only

• Step 17: Starting Natural ISPF for the First Time

• Step 18: Installation Verification

• Step 19: Moving Incore Database Applications to Production Environment

Step 1: Prepare, Convert, Assemble, and Link the License File

(Job I007, Steps 2001, 2002, 2004)

You must install a valid Natural ISPF license file.

For detailed information on the license file and product licensing, see Software AG Mainframe Product Licensing.

1. Copy the license file from the supplied installation medium to disk or transfer it from the PC as described in Transferring a License File from PC to a z/OS Host Using FTP in Software AG Mainframe Product Licensing.

2. Check, convert, assemble, and link the license file:

   Step 2001	Check license file ISPvrs.LICS. This job runs the CHECK function of the LICUTIL license utility (see below).
   Step 2002	Convert license file into an assembler source. This job runs the MAKE function of the LICUTIL license utility (see below).
   Step 2004	Assemble and link the assembler source to generate load module ISPLIC. This module is then linked to the nucleus.

3. The functions and option settings provided by LICUTIL are described in Using the License Utility: LICUTIL in Software AG Mainframe Product Licensing.

Step 2: Copying the Medium Contents to Disk

To load the Natural ISPF installation medium, proceed as follows:

For z/OS:

Copy the data sets from the supplied installation medium to your disk before you perform the individual installation procedure for each component to be installed.

The way you copy the data sets depends on the installation method and the medium used:

• If you use System Maintenance Aid (SMA), refer to the copy job instructions provided in the System Maintenance Aid documentation.

• If you are not using SMA and want to copy the data sets from CD-ROM, refer to the README.TXT file on the CD-ROM.

• If you are not using SMA and want to copy the data sets from tape, follow the instructions in this section.

This section explains how to copy all data sets from tape to disk.

• Step 1: Copy Data Set COPY.JOB from Tape to Disk
• Step 2: Modify hilev.COPY.JOB on Your Disk
• Step 3: Submit COPY.JOB

Step 1: Copy Data Set COPY.JOB from Tape to Disk

• Modify the following sample job according to your requirements:

  //SAGTAPE JOB SAG,CLASS=1,MSGCLASS=X
  //* ---------------------------------
  //COPY EXEC PGM=IEBGENER
  //SYSUT1 DD DSN=COPY.JOB,
  // DISP=(OLD,PASS),
  // UNIT=(CASS,,DEFER),
  // VOL=(,RETAIN,SER=tape-volser),
  // LABEL=(2,SL)
  //SYSUT2 DD DSN=hilev.COPY.JOB,
  // DISP=(NEW,CATLG,DELETE),
  // UNIT=3390,VOL=SER=disk-volser,
  // SPACE=(TRK,(1,1),RLSE),
  // DCB=*.SYSUT1
  //SYSPRINT DD SYSOUT=*
  //SYSIN DD DUMMY
  //

  where:

  tape-volser is the VOLSER of the tape, for example: T12345,
  hilev is a valid high-level qualifier, and
  disk-volser is the VOLSER of the disk.

• Execute the job to copy the data set COPY.JOB to your disk.

Step 2: Modify hilev.COPY.JOB on Your Disk

• Modify hilev.COPY.JOB according to your requirements:

  Set EXPDT to a valid expiration date, for example, 99365.

  Set HILEV to a valid high-level qualifier, for example, USERLIB.

  Set LOCATION to a storage location, for example, STORCLAS=ABC or UNIT=3390,VOL=SER=USR123.

Step 3: Submit COPY.JOB

• Execute hilev.COPY.JOB to copy single, multiple, or all data sets to your disk.

Step 3: Loading System Programs and Error Messages

Load files ISPvrs.INPL and ISPvrs.ERRN. They load objects into the following Natural libraries (if a library does not yet exist, it is created):

^* The libraries marked with an asterisk (*) are created only, if Natural Security is installed at your site (see also Natural Security Definitions).

Job I061

Load the files using Job I061, Steps 2000 (INPL) and 2001 (ERRN).

For All Platforms on which Natural Security is Installed

If return code 5500 or 828 is issued, the job may not be authorized to make all Natural Security entries at your site. If this happens, reload program INTISPS1 from the INPL and run it in library SYSTEM in online Natural to ensure that all security entries are made.

Step 4: Loading Predict Data

All Natural ISPF files used in Incore database examples are documented in Software AG's repository Predict. The ISPvrs.DATA data set on the installation medium contains these Predict data that can be loaded with the MIGRATE utility in Predict. This is optional.

The MIGRATE utility is described in the Predict Reference documentation. Use Job I200, Step 2000 to load the file.

Step 5: Modifying the Online Natural Parameter Module

Check the NATPARM module to see if it contains the following definitions. If not, add them:

^* These definitions are required only if the Entire System Server (formerly Natural Process) is installed. Note also that the NTDB definitions must always be at the end of the NATPARM module. It is important that even if your Entire System Server default node ID is different from 148, the entry, NTDB PROCESS 148, has to remain unchanged here.

^** All Incore database examples use this DBID. If 147 cannot be used at your site, all Incore database DDMs (ISP-IDB*) must be recataloged with the new value specified here. All Incore database example programs (IDB* and VER* in the example library) must also be recataloged accordingly.

If the specified SSIZE value is not available when Natural ISPF is invoked, no Natural ISPF command is accepted (the message Invalid command appears). If this happens, check whether SSIZE is available using the Natural command BUS.

Notes:

1. If the IMPORT/EXPORT PC functions are to be used with Entire Connection, Workfile 7 must be assigned to PC or PC3 (for example, NTWORK (7),AM=PC). The default Workfile 7 can be modified (see the description of the Import/Export Exits in the Natural ISPF Administration Guide, section User Exits).

2. Use the NTPRINT macro to define at least Printers 1 and 2 (see the Natural Parameter Reference documentation).

   • If you specify NTPRINT (1,2),AM=OFF or the equivalent PRINT=OFF, the WORKPOOL and BROWSE-VIEW functions are not available. Of course, you can also specify the printer definitions online using the PRINT parameter which can complement or override the NTPRINT definitions.

   • You can specify any access method of your choice, but when using Natural ISPF in an online environment, you should specify the options OPEN=ACC, CLOSE=OBJ (it may be acceptable for batch environments to use the options OPEN=INIT, CLOSE=FIN).

Job I080

Reassemble and link the NATPARM module when modified (JCL is contained in member NATI080 in the Natural installation job library).

Step 6: Modifying Natural VSAM Parameters

Set parameter KEYLGH in macro NVSPARM to 126. Then reassemble and link the macro using Job NVSI055, Steps 1400 and 1401. This job can be found in library NATvrs.JOBS or NVSvrs.JOBS.

Step 7: Assembling the Parameter Modules for the ESX Component

Please refer to the section Installing the Entire Systems Server Interface in the Natural Installation documentation for Mainframes to install the ESX component.

Step 8: Linking the Gateway Modules for the ESX Component

Please refer to section Installing the Entire Systems Server Interface in the Natural Installation documentation for Mainframes to install the ESX component.

Step 9: Relinking Natural with Natural ISPF

Please refer to the section Natural Installation documentation for Mainframes to install the ESX component.

Modules required if Natural VSAM system files are used (from Natural VSAM library):

Step 10: Loading / Migrating the Natural ISPF Versions File

The Natural ISPF versions file is used to store "update decks" for edited Natural members and PDS members. This means that if versioning is active, previous versions of these object types are kept when selected for editing and can be retrieved.

You can use an Adabas file or a VSAM file as versions file.

Loading a Versions File

Follow these instructions if you do not yet have a versions file.

Adabas Versions File

Load the empty Natural ISPF versioning file (data set ISPvrs.SYS1) using the ADALOD utility. All versioning data is stored in this file. The ADALOD parameter ISNREUSE must be set to YES:

ISNREUSE=YES

The file number of the versions file can be freely chosen and must be entered in the Natural ISPF parameter screen of the configuration option. See the Natural ISPF Administration Guide, section System Configuration, subsection Natural ISPF Parameters.

If the versions file is to be protected by an Adabas password, the password must be defined to Natural using the following NTFILE macro:

NTFILE ID=205,DBID=n,FNR=m,PASSW=password

Recommended ADALOD Parameters

The following ADALOD parameters are recommended:

I050 2000 ADALOD FOR ISPF VERSIONING FILE

Job I050 step 2000

Additional parameters can be found in Job I050, Step 2000.

VSAM Versions File - z/OS only

1. Add the following statement to the Natural parameter module:

   NTFILE ID=205,DBID=n,FNR=m,PASSW=ISPV

   where:

   n is any VSAM DBID

   m is any number

   ISPV is DD(FCT,DLBL) name of the VSAM file.

   Note
   Due to the usage of the NTFILE/LFILE parameter, regardless if with or without PASSW, the values for VERSIONS DBID and VERSIONS FNR in the Natural ISPF parameters are ignored, but some values must be set in these fields to activate versioning. It is highly recommended to use the correct numbers to prevent confusion.

2. The module NVSISPV must be linked to the Natural for VSAM nucleus.

   If you wish to use a VSAM file as versions file, sample JCL for defining the VSAM cluster can be found in Job I008, Step 2000.

3. Natural for VSAM parameter KEYLGH must be set to 126 (minimum value).

4. The file must be initialized by loading the data set ISPvrs.VINI with VSAM repro. See Job I008, Step 2001.

Under CICS

If you are defining a VSAM versions file under CICS, add an FCT entry. For an example, see Job I005.

Under Com-plete

If you are defining a VSAM versions file under Com-plete, catalog the VSAM versions file as follows:

• Under Com-plete, use the CA function of the UFILE utility, and add the card:

  DDN=ISPV,VS,R,U,A,MACR=(SEQ,DIR,KEY,SKP,NSR),MRPL=8

  You must also add the appropriate DD cards to the Com-plete startup procedure. For example:

  ISPV  DD  SAGLIB.VSAM.ISPVERS,DISP=SHR

Under TSO

If you are defining a VSAM versions file under TSO, add the following statement to your CLIST for Natural:

ALLOC F(ISPV) DA('SAGLIB.VSAM.ISPVERS') SHR

Step 11: Loading the Natural ISPF Container File

The Natural ISPF container file can be used to store Incore database files, which can then be retrieved and manipulated in the Incore database.

You can use an Adabas file or a VSAM file as container file.

Adabas Container File

Omit this step if you already have a Natural ISPF container file.

Load the empty Natural ISPF container file (data set ISPvrs.SYS2) using the ADALOD utility. All Incore database data is stored in this file.

Recommended ADALOD Parameters

Following ADALOD parameters are recommended:

I050 2001 ADALOD FOR ISPF CONTAINER FILE

The file number of the container file can be freely chosen and must be defined using the NTFILE parameter in the NATPARM module.

If the container file is to be protected by an Adabas password, the password must be defined to Natural using the following NTFILE macro:

NTFILE ID=186,DBID=n,FNR=m,PASSW=password

Job I050 Step 2001

Additional parameters can be found in Job I050, Step 2001.

VSAM Container File - z/OS only

1. Add the following statement to the Natural parameter module:

   NTFILE ID=186,DBID=n,FNR=m,PASSW=ISPC

   where:

   n is any VSAM DBID

   m is any number

   ISPC is DD(FCT,DLBL) name of the VSAM file.

2. The module NVSISPC must be linked to the Natural for VSAM nucleus.

   Sample JCL for defining the VSAM cluster can be found in Job I008, Step 2002.

3. Natural for VSAM parameter KEYLGH must be set to 126 (minimum value).

4. The file must be initialized by loading the data set ISPvrs.VINI with VSAM repro. See Job I008, Step 2003.

Under CICS

If you are defining a VSAM container file under CICS, add an FCT entry. For an example, see Job I005, Step 2203.

Under Com-plete

If you are defining a VSAM container file under Com-plete, catalog the VSAM container file as follows:

DDN=ISPC,VS,R,U,A,MACR=(SEQ,DIR,KEY,SKP,NSR),MRPL=8

You must also add the appropriate DD cards to the Com-plete startup procedure. For example:

ISPC  DD  SAGLIB.VSAM.ISPCONT,DISP=SHR

Under TSO

If you are defining a VSAM container file under TSO, add the following statement to your CLIST for Natural:

ALLOC F(ISPC) DA('SAGLIB.VSAM.ISPCONT') SHR

Step 12: Natural Security Definitions

All security entries for applications and files are made automatically. The entries are not protected and may thus require appropriate modification by the system administrator.

1. Define the applications:

   Application	Description
   SYSISPS1*	ISPF system tables / menus / profiles
   SYSISPFU*	ISPF user tables / menus / profiles
   SYSISPH1	ISPF system help texts
   SYSISPDB	ISPF Incore database modules
   SYSISPX*	ISPF exit sources
   SYSISPXC*	ISPF user exits for Com-plete
   SYSISPE	ISPF example library
   SYSISPI	ISPF system interface library
   SYSISPXU*	ISPF user-defined exit sources
   SYSISPHU*	ISPF user-defined help texts
   SYSISPIU*	ISPF user-defined information (UINFO)

   ^* To increase security, the applications marked with an asterisk (*) should be defined as people-protected (private) and be linked to the system administrator. Startup programs and error transactions must not be defined, and all applications should allow REPORT mode.

   Note
   All libraries ending with U are empty, as they are to be used for customized menus and site-specific help and online information. The content of all other libraries is supplied by Software AG. However, INPL will load modules COPYSYS and ISP-CvrsN into library SYSISPFU to ensure proper execution of sample modules.

2. Define the following files in Natural Security as public:

   ISP-IDB-ADRESSEN
   ISP-IDB-CLASS
   ISP-IDB-DIRECTORY
   ISP-IDB-EMPL-LIST
   ISP-IDB-EMPLOYEES
   ISP-IDB-INCOME
   ISP-IDB-MUSIC
   ISP-IDB-NPRUSER
   ISP-IDB-TEXT
   ISP-IDB-MOVIES
   ISP-IDB-PERSON
   ISP-IDB-MENU-LINES
   ISP-IDB-MENU-CMDS
   ISP-IDB-TIMER

   These files are used in Incore database examples.

3. From the Natural Security Administrator Services Menu, select code G (General Options) and set the field Free access to functions via interface subprograms to value Y.

Step 13: Required Interfaces to Other Software AG Products

Library SYSISPI contains some interface programs to other Software AG products. Execute program INSTALL from this library to ensure that all required interface programs are installed properly.

The INSTALL program makes sure that all required interface programs are installed properly by copying them from the library SYSISPI to SYSLIB and/or SYSLIBS. In addition INSTALL copies your user exits from the user exit library to SYSLIB, thus ensuring that Natural ISPF will not be invoked without your user exits being active.

Before executing the program INSTALL in a Natural Security environment, be sure that the prerequisites mentioned in Note 1 (see below) are fulfilled.

The following screen will be displayed by INSTALL, fill in the input fields and press PF5 to start execution:

Please fill in fields and press PF5 to start
 08:38:02                   N A T U R A L   I S P F               07-11-15
                             Installation Program
  
 Installation environment
   Natural version  ... FNAT DB     ... FNR    ...
   PREDICT version  ...
   Natural security ...
  
 Installation parameters
   Enter printer to trace activities. . . . .  :
   Copy user exits from library . . . . . . .  :   SYSISPXU
   Copy user profiles from file number  . . .  :      ...
   Do you want N-ISPF to be the only
   user interface (no MAINMENU any more) (Y/N) :   N
  
  
  
  
  
  
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                  END         OK

The meaning of the input fields:

Depending on the version of the products installed, the following programs will be copied to SYSLIB and/or SYSLIBS:

* Last program to be copied, used for verification of successful execution of the INSTALL program.

Notes:

1. Before executing the INSTALL program, check whether the libraries SYSISPFU, SYSISPS1, SYSLIB and SYSLIBS are defined in Natural Security, and verify that you are authorized to access them.
2. All user exits are copied to SYSLIB (members IS* from SYSISPX or from the library specified in the screen above).
3. If the FNAT system file is protected by an Adabas password, INSTALL prompts for the password. If the FNAT system file resides in a VSAM file, INSTALL prompts for the FNAT name as defined in the NATPARM parameter module.
4. Some of the copy operations performed during execution of the INSTALL program are done as "copy without replacement". For this reason, any NAT4810 messages reported during execution of the INSTALL program are normal and can be ignored.
5. If the INSTALL program has not executed successfully, Natural ISPF cannot be started.

Step 14: Optional Interfaces to Software AG Products

Con-nect Application Programming Interface

If you intend to transfer files to and from Con-nect, or if you want to activate the Con-nect subsystem of Natural ISPF, the application programming interface must be copied: you must copy all objects starting with Z from the library SYSCNT2 to the library SYSLIBS.

Notes:

1. The Con-nect system file must be assigned to a physical database file.
2. Library SYSLIB may also contain old programs beginning with Z from previous installations. All these interface programs must be deleted to ensure that Natural ISPF calls the newest versions.

Extended Natural / USPOOL Interface under Com-plete

If you are installing Natural ISPF under Software AG's TP-Monitor Com-plete, you also have the option of installing the extended Natural/USPOOL interface. This interface enables Natural ISPF users to use logical printer drivers defined in Com-plete, when printing Natural ISPF objects. If you choose not to install this interface, it is still possible to route Natural ISPF printouts to printing devices defined within Com-plete, but users will not be able to use logical printer drivers.

No specific installation steps are required. It is sufficient to activate the USPOOL interface by setting APPLYMOD 22, as described in the Natural ISPF Administration Guide.

Step 15: CA Librarian Interface - z/OS only

To activate the CA Librarian interface, you must assemble and link the Entire System Server (formerly Natural Process) module NATPAML into the Entire System Server load library. For instructions, refer to the section Installation in the Entire System Server documentation.

Step 17: Starting Natural ISPF for the First Time

Notes:

1. If you are using the Natural ISPF user interface, you can omit this step.
2. The PS parameter must not exceed 43. If it does, Natural ISPF will display a warning at startup time: NATURAL />>> Page size (parameter PS) must not exceed 43. Natural ISPF is designed to work with the most common display devices. As it accesses the SAG Editor frequently, the whole screen is kept in arrays which are dimensioned to work with terminals. A PS value greater than 43 will result in runtime errors or dumps of the executing Natural nucleus.

To start Natural ISPF, enter the command:

SPF

in the command line of your Natural session. This displays the Natural ISPF main menu on your terminal screen. Select the ADMIN (Administrator Functions) option from the Main Menu. The Administrator Menu appears.

All available administrator functions are described in the Natural ISPF Administration Guide.

Starting Natural ISPF in Batch

Natural ISPF can be used in batch environments similar to online sessions. However, there are some prerequisites:

1. The entire SAG Editor environment must be linked to the Natural nucleus, and the necessary files (Editor Work File) and the correct parameters must be supplied, in particular:

2. The PS parameter must not exceed 43. See note above.

Step 18: Installation Verification

To verify whether the installation of Natural ISPF was successful, issue the following commands in the Natural ISPF Main Menu:

LOGON SYSISPE
PLAY MAC VERIFY

This starts a Natural ISPF command script which guides you through a test cycle of various Natural ISPF functions. First, a help screen appears that tells you how to control the test run and which components are tested. Press PF3 to continue; the next screen is the output of the Natural ISPF TECH command.

Step 19: Moving Incore Database Applications to Production Environment

To move Incore database applications to your production environment, proceed as follows:

1. Repeat all steps in this installation except the following:

   • Do not load the Natural ISPF INPL data set.

   • Do not load the Natural ISPF versions file.

   • Natural Security definitions are not required.

   • Do not execute the Natural ISPF INSTALL program.

   • Neither the Con-nect interface nor the USPOOL and CA Librarian interfaces are required.

2. Use SYSMAIN to copy all objects from SYSISPDB to SYSTEM (or another STEPLIB of the application that uses the CALLNAT interface) in the production environment, or define SYSISPDB as STEPLIB for your application.

3. If an explicit creation of an incore file is used in your application, you also need the file (DDM) in your production environment. Use SYSMAIN to copy it.

4. Define library SYSLIBS as steplib for your Incore database applications.