This document describes step by step how to install Natural under the operating system z/OS using Adabas system files.
The following topics are covered:
See also z/OS Environment in the Natural Operations documentation.
For installation-related information on Unicode and code page support, refer to Configuration and Administration of the Unicode/Code Page Environment in the Unicode and Code Page Support documentation.
Notation vrs or vr: If used in the following document, the notation vrs or vr stands for the relevant version, release, system maintenance level numbers. For further information on product versions, see Version in the Glossary.
A supported version of the z/OS operating system must be installed. For the supported versions of the operating systems, refer to Operating/Teleprocessing Systems Required in the current Natural Release Notes for Mainframes.
A supported version of Adabas must be installed. For the supported versions, refer to Natural and Other Software AG Products in the current Natural Release Notes for Mainframes.
As a rule of thumb, each major Software AG product requires approximately 20 MB space in the Adabas database to store the Natural objects supplied by Software AG.
The installation tape contains the datasets listed in the table below. The sequence of the datasets and the number of library blocks needed are shown in the Report of Tape Creation which accompanies the installation tape.
| Dataset Name | Contents |
|---|---|
NATvrs.LICS |
Natural License Key File. For further information
on license key file, license key file installation, product license check and
product license check FAQs, see Licensing Natural.
If a license key file is supplied as an e-mail attachment, see Transferring the License Key File from PC to Host with FTP. |
NATvrs.SYSF |
Empty Natural system file |
NATvrs.ERRN |
Natural error messages |
NATvrs.LOAD |
Natural load modules |
NATvrs.OBJS |
Natural object modules |
NATvrs.SRCE |
Natural source modules and macros |
NATvrs.JOBS |
Example installation jobs |
NATvrs.LDEL |
Instructions to delete Natural system objects of Version 4.1 |
NATvrs.INPL |
Natural system objects |
NATvrs.EXPL |
Natural example objects |
If you are using SMA, refer to the System Maintenance Aid documentation (included in the current edition of the Natural documentation CD).
If you are not using SMA, follow the instructions below.
This section explains how to:
Copy dataset COPY.JOB from tape to disk.
Modify this dataset to conform to your local naming conventions.
The JCL in this dataset is then used to copy all datasets from tape to disk.
If the datasets for more than one product are delivered on the tape, the
dataset COPY.JOB contains the JCL to unload the datasets for all
delivered products from the tape to your disk.
After that, you will have to perform the individual install procedure for each component.
The dataset COPY.JOB (Label 2) contains the JCL to unload all
other existing datasets from tape to disk. To unload COPY.JOB, use
the following sample JCL:
//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-volume), // LABEL=(2,SL) //SYSUT2 DD DSN=hilev.COPY.JOB, // DISP=(NEW,CATLG,DELETE), // UNIT=3390,VOL=SER=volume, // SPACE=(TRK,(1,1),RLSE), // DCB=*.SYSUT1 //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //
where:
hilev is a valid high level
qualifier
tape-volume is the tape
volume name, for example: T12345
volume is the disk volume
name
Modify the COPY.JOB on your disk to conform to your local
naming conventions and set the disk space parameters before submitting this
job:
Set HILEV to a valid high level qualifier.
Set LOCATION to a storage location.
Set EXPDT to a valid expiration date.
Submit COPY.JOB to unload all other datasets from the tape to
your disk.
If a license key file is supplied as an e-mail attachment, you must
transfer the attached license key file
natvr.xml from the PC to the mainframe,
using native FTP commands.
 |
Warning: Using utilities instead of native FTP commands for the license key file transfer may corrupt the license key and thus prevent Natural from execution later on. This applies for example to file transfer based on 3270 terminal emulations that do not provide a true binary file transfer, but convert specific characters. |
To transfer a license key file from the PC to the mainframe, perform the following steps:
Save the product license key file e-mail attachment on your PC hard disk.
Open a command prompt window. In the command prompt window, change to the directory where you saved the product license key file.
Start an FTP session for communication with the z/OS host:
ftp host-name
Where host-name is the name of
the z/OS host.
Enter your z/OS host login ID and password.
Once the FTP session has been established, specify the z/OS file system and dataset prefix for the license key file:
ftp>cd 'hilev'
Switch to binary data mode (the license key file must retain its ASCII format during the transfer):
ftp>binary
Specify that the dataset for the license key file must be written with
RECFM=FB and LRECL=80.
ftp>quote site RECFM=FB LRECL=80 BLKSIZE=4000
Note:RECFM=F is also supported for product license key
files.
Copy the license key file as a dataset on the z/OS system.
ftp>put natvr.xml NATvrs.LICS
This command will create a dataset called
hilev.NATvrs.LICS.
If you requested a prefix of NATURAL, the dataset name
would be: NATURAL.NATvrs.LICS.
The dataset will have RECFM=FB, LRECL=80, and
the license key information stored in the dataset will be in ASCII format.
Stop your FTP session by entering:
ftp>quit
Using PROGRAM NATLICAM, convert dataset
hilev.NATvrs.LICS
into an Assembler input file.
Assemble/link into a linkable module. This module is linked (Job I060) to the Natural nucleus.
(Job I007, Steps 0101, 0102 and 0104)
| Job I007, Step 0101 | Allocate temporary dataset for license key
module (NATLIC)
|
| Job I007, Step 0102 | Convert license key file
(NATvrs.LICS).
|
| Job I007, Step 0104 | Assemble and link license key module (NATLIC).
|
(Job I009, Step 1200, 1210, 1220, 1250)
Link the following Natural modules to an Authorized Program Facility (APF) library:
NATGBP42 |
Required if you want to install a global buffer pool. |
NATASM42 |
Required if you want to install an Authorized Services Manager
(ASM).
You must use the ASM in the following cases:
|
NATRSM42 |
Required if you want to install a Natural Roll Server.
You must use the RSM in the following cases:
See also Natural Roll Server Operation in the Operations documentation. |
| RPC Server Front-End |
Required if you want to use impersonation with the Natural Remote Procedure Call (RPC). If you use SMA: Define the name
of the RPC server front-end in the parameter
If you do not use SMA: The name of the RPC server front-end is freely selectable and is specified in the link-edit step of Job I009, Step 1250. It is recommended to link the RPC server front-end into an
APF-authorized |
(Job I015, Steps 0100, 0101, 0102, 0104)
| Step | Creates job | Function |
| 0100 | GBNASTRT |
Start Natural global buffer pool. |
| 0101 | GBNASTOP |
Stop Natural global buffer pool. |
| 0102 | GBEDSTRT |
Start editor global buffer pool. |
| 0104 | GBEDSTOP |
Stop editor global buffer pool. |
These steps are only required if you wish to use a global buffer pool.
Create and start the jobs GBNASTRT and
GBEDSTRT before using Natural.
For further information on the global buffer pool, see Natural Global Buffer Pool in the Natural Operations documentation.
Installation of the Authorized
Services Manager is mandatory if the z/OS parameter
ALLOWUSERKEYCSA(NO) applies by default or has explicitly been
specified in SYS1.PARMLIB(DIAGxx),
(Job I050, Step 0100)
If you are installing into an existing Natural 4.1 FNAT file, skip this
step.
Load the empty Natural system file (dataset
NATvrs.SYSF) using the ADALOD utility.
This file will contain all Natural objects supplied by Software AG. Its size depends on the number of products to be installed later. As a rule of thumb, 20 MB can be assumed for each major Software AG product.
The following ADALOD parameters must not be altered:
ISNREUSE=YES
To avoid Natural errors NAT9988 and NAT7397 after reorganization of the FNAT
system file using ADAULD/ADALOD, the parameter USERISN
should be set to YES.
The file number fnat of the
FNAT system file can be chosen as described under Natural profile
parameter FNAT in the Natural
Parameter Reference documentation.
(Job I050, Step 0101)
You have the following options:
You can use an existing Version 4.1 FUSER file, then you can skip this
step.
You can use a new FUSER file for Version 4.2.
You can use an existing Version 4.1 FUSER file to be shared by Versions
4.1 and 4.2.
You can use an existing Version 4.1 FUSER file to be used by Version 4.2
only.
For the use of a new and empty FUSER system file for Natural Version 4.2, no
additional system-file-related actions are necessary.
If you do not want to share the FUSER system file, proceed as
follows:
Load the empty Natural user file contained in dataset
NATvrs.SYSF using the ADALOD utility.
In this file, all user-written Natural programs are stored.
The following ADALOD parameters must not be altered:
ISNREUSE=YES
The file number fuser of the FUSER system file
can be chosen as described under Natural profile parameter FUSER in the Natural
Parameter Reference documentation.
If you want to use the existing Natural Version 4.1 FUSER system file and
you do not want to share the FUSER system file, skip this step.
If you use an existing Natural Version 4.1 FUSER system file to be shared by
Natural Versions 4.1 and 4.2, you must upgrade your Natural Version 4.1
installation to Version 4.1.4.
Natural Version 4.1.4 Service Pack I003 or a subsequent Service Pack is required. Service Pack I003 and all subsequent Service Packs contain all the necessary Version 4.1 based solutions for Natural Version 4.2.
The USR* programs from the delivered library SYSEXT run in a special mode.
As a result, the USR* programs do not need to set further steplibs to execute
related objects for processing. This reduces the impact on the Natural buffer
pool search logic and improves the performance significantly if user exits are
used extensively within user written applications.
It is necessary that the user exits are cataloged with Natural Version 4.2. This implies that the user exits cannot be executed with Natural Version 4.1.
Usually, the access of USR* programs by an application requires that the
user application programming interfaces be copied from library SYSEXT to either
the application libraries on the FUSER system file or to library SYSTEM on the
FUSER system file or to library SYSTEM on the FNAT system file, respectively,
or any other library which is defined as steplib for the application. Library
SYSEXT can also be used as steplib. Due to the fact that the delivered user
application programming interfaces will always be cataloged with the latest
Natural version, we recommend that the user application programming interfaces
should reside on the FNAT system file. This will ensure that the right version
is executed and will separate user written applications from Software AG
modules.
If applications which call user application programming interfaces should run with both Natural Version 4.1 and Natural Version 4.2, it must be made sure that the user application programming interfaces delivered with the corresponding Natural version are used.
The following scenarios may be considered:
If the same FUSER system file shall be used in a Natural Version 4.1 and
Version 4.2 environment in parallel the following steps are recommended:
Remove all USR* modules you have copied from library SYSEXT into
application libraries on your FUSER system file.
In both environments, copy the used USR* modules from library SYSEXT to
library SYSTEM on the corresponding FNAT system file.
Alternatively, the USR* modules can be moved to another system library on
FNAT which then must be defined as steplib, or library SYSEXT can be used as
steplib for the applications. Then automatically in both environments the right
versions of the user application programming interfaces are executed.
If you want to use the existing Natural Version 4.1 FUSER system file and
you do not want to share the FUSER system file, then it is still possible to
replace all USR* modules you have copied from library SYSEXT into application
libraries with the new USR* objects from the Version 4.2 library SYSEXT.
But the preferred way is to remove all user application programming
interfaces on the FUSER system file and copy the used user application
programming interfaces from library SYSEXT to library system of the FNAT system
file or use a SYS library on FNAT as steplib.
If you want to port existing applications to a new FUSER system file, copy
all application objects but no Software AG USR* objects to the new FUSER system
file. Then proceed as described in the scenario above.
The FIND function of the Natural utility SYSMAIN can be used to search for
all USR* modules stored in a specific library on the FUSER system file or
across the whole system file. In addition, Predict cross reference data can be
used to determine all referenced user application programming interfaces.
The file number fuser of the
FUSER system file can be chosen as described under Natural profile
parameter FUSER in the Natural
Parameter Reference documentation.
(Job I050, Step 0102)
The scratch-pad file (which is a Natural-internal system file) can be used exclusively by the new Natural version or it can be shared by different versions of Natural.
If you do not want to use a scratch-pad file, skip this step.
If you do want to use a scratch-pad file; that is, if you want to use
read-only system files (profile parameter ROSY=ON), see also
Natural Scratch-Pad File in the Natural
Operations documentation, proceed as follows:
Load the empty scratch-pad file contained in dataset
NATvrs.SYSF, using the ADALOD utility as described
below.
The following ADALOD parameter must not be altered:
ISNREUSE=YES
For the optional scratch-pad file inclusion, the following NATPARM parameters must be added or, if already present, updated with:
LFILE=(212,dbid,fnr) ROSY=ON
If you use SMA: To be able to use a
read-only system file, you have to set the parameter
NAT-SCRF to Y and
ROSY to ON.
(Job I050, Step 0103)
Skip this step:
if you want to install Predict (in this case, use the corresponding installation step in the Predict Installation documentation), or
if you want to use an existing FDIC system file (an existing FDIC system
file can be shared by Natural Versions 4.1 and 4.2), or
if you do not use your own FDIC system file.
Load the empty FDIC system file contained in dataset
NATvrs.SYSF using the ADALOD utility, as described
below.
The following ADALOD parameters must not be altered:
ISNREUSE=YES
The file number fdic of the
FDIC system file can be chosen as described under Natural profile
parameter FDIC in the Natural
Parameter Reference documentation.
Skip this step,
if you do not use Natural Security, or
if you want to use an existing FSEC system file, or
if you do not want to use an own FSEC system file.
If you use Natural Security: Refer to Installing Natural Security.
(Job I055, Step 0100 or 0103)
The source program NATOS contains a call to the macro
NTOS which generates the Natural z/OS interface.
Job I055, Step 0100, do the IEBUPDATE.
Job I055, Step 0103, assemble and link NATOS.
Set the parameters in the source of the module NATOS to
meet your requirements.
For a description of the Natural for z/OS generation parameters
contained in the macro NTOS, refer to
NTOS
Macro - Generation Parameters for Natural under z/OS in
the Natural Operations documentation.
Assemble and link the Natural z/OS interface module NATOS
contained in the dataset
hilev.NATvrs.SRCE.
(Job I055, Step 0110)
This step is only required if you need to change the delivered
NATCONFG module, for example, to adapt the
NTDVCE
macro definition to your requirements.
Change and assemble the source contained in the dataset
hilev.NATvrs.SRCE.
Link the resulting Natural configuration module
(NATCONFG) to the Natural nucleus when you link the Natural
nucleus (see below).
For more information on the configuration tables in
NATCONFG, refer to Natural Configuration
Tables in the Natural Operations
documentation.
(Job I060, Steps 0010, 0015)
Create the batch Natural parameter module.
The following parameters in the parameter module must be modified for the installation:
FNAT=(dbid,fnat) FUSER=(dbid,fuser)
For dbid, fnat and fuser, use the values you specified when loading the system files (see above).
Global Natural Buffer Pool: If you
wish to use a global Natural buffer pool, specify the parameter macro
NTBPI
with the name of the global Natural buffer pool and set the profile parameter
SUBSID in
all your Natural parameter modules.
If you use SMA: Define the name of the
global Natural buffer pool in SMA parameter
NAT-GLOBAL-BP.
For all other parameters: You can generally use the default values. Modify only the values of those parameters whose default values do not meet your requirements.
For a description of the individual parameters contained in the parameter module, refer to the Parameter Reference overview in the Natural Parameter Reference documentation.
Assemble and link the parameter module.
When linking the Natural nucleus, you have the following alternatives:
Link a batch front-end (Job I060, Step 0020) and link a shared nucleus (Job I060, Step 0105), or link a non-shared nucleus (Job I060, Step 0020).
Link a batch front-end (Job I060, Step 0020)
Do not link the batch front-end with the linkage editor option RENT.
With the INCLUDE instruction for the parameter module,
specify the name of the Natural parameter module you have created before.
The following modules must be included (include module
NATOS first):
| Module | Function |
|---|---|
NATOS |
Batch Natural driver |
NATWKFO |
Work file support |
PR001B |
Generated parameter module |
ADAUSER |
Adabas link module |
To access the shared nucleus, ensure that the NATPARM
parameter NUCNAME contains
the name of the module linked in Job I060, Step 0105.
Link a shared nucleus (Job I060, Step 0105)
For a list of the modules included, see Natural Shared Nucleus under z/OS and z/VSE in the Natural Operations documentation.
If IBM error IEW2641S is returned when linking the shared nucleus, link the shared nucleus into a PDSE instead of a PDS.
Or:
Link a non-shared nucleus (Job I060, Step 0020)
Do not link the non-shared nucleus with the linkage editor option RENT.
If you use SMA:
Ensure that SMA parameter SHARED-NUC is
set to N (no). All the modules are then automatically linked in
Step 0020.
If you do not use SMA:
Merge all INCLUDE statements and corresponding DD
cards from Job I060, Step 0105 (shared nucleus) into Job I060, Step 0020
(front-end).
Link the executable Natural nucleus.
If IBM error IEW2641S is returned when linking the non-shared nucleus, link the non-shared nucleus into a PDSE instead of a PDS.
This step is optional but recommended to avoid data inconsistencies.
If you are using a Version 4.1 Natural FNAT system file,
you can delete obsolete Version 4.1 Natural objects.
If you are using SMA: Set the SMA
parameter NAT-FNAT41 to Y (yes).
If only base Natural Version 4.1 is installed
Delete the Version 4.1 Natural objects by loading the
NATvrs.LDEL data set with the Natural
INPL utility.
(Job I061, Step 0010)
If Natural for DB2 Version 4.1 is installed
Delete the Version 4.1 Natural for DB2 objects by loading the
NDBvrs.LDEL data set with the
INPL utility.
(Job I061, Step 0016)
See also Delete Natural for DB2 Objects in the Natural for DB2 documentation.
If Natural Review Version 4.1 is installed
Delete the Version 4.1 Natural Review objects by loading the
RNMvrs.LDEL data set with the
INPL utility.
(Job I061, Step 0026)
See also Delete Natural Review Objects in the Natural Review documentation.
If Natural Security Version 4.1 is installed
Delete the Version 4.1 Natural Security objects by loading the
NSCvrs.LDEL data set with the
INPL utility.
(Job I061, Step 0099)
See also Delete Natural Security Objects in Installing Natural Security.
(Job I061, Step 0100)
Use the Natural INPL utility to load the Natural
system objects (dataset NATvrs.INPL)
into the Natural system files.
(Job I061, Step 0102)
Load the English Natural error messages file (dataset
NATvrs.ERRN) using the program
ERRLODUS.
In addition to the English error message short and long texts, error message
short texts in German language (ULANG=2) are loaded. Use the
program ERRUPPER
to convert the error message texts to upper case. Both programs are described
in the Natural SYSERR Utility documentation.
NCJvrs.INPL)
(Job I061, Step 8300)
This step is only required if you wish to replace the English error message long texts with their Japanese equivalents.
The Natural error message long texts in Japanese language are contained in the Natural Japanese Language Pack. This is a separate product (product code NCJ) that can be loaded optionally. If you do not load the Natural error message long texts in Japanese language, English error message long texts will appear.
Use the Natural utility INPL to load the Japanese error
message long texts (dataset
NCJvrs.INPL) into the Natural system
files.
NCJvrs.ERRN)
(Job I061, Step 8302)
This step is only required if you wish to load the error message short
texts in Japanese language (ULANG=59).
The Natural error message short texts in Japanese language are contained in the Natural Japanese Language Pack. This is a separate product (product code NCJ) that can be loaded optionally. If you do not load the Natural error message short texts in Japanese language, English error message short texts will appear.
Use the program
ERRLODUS
described in the Natural SYSERR Utility documentation to
load the error message short texts (dataset
NCJvrs.ERRN) into the Natural system
file.
(Job I061, Step 0103)
Use the Natural utility INPL to load the Natural example
objects (dataset NATvrs.EXPL) into the
Natural system file.
(Job I200, Step 0101)
This step is only required if you wish to use the Natural Roll Server.
Note:
If you plan to use an existing Roll File of a previous version, it
is sufficient to execute the NATRSRFI RESET function. See
Natural Roll Server
Operation in the Natural Operations
documentation.
Create and start the job FORMRF1 before using
Natural.
For further information on different types of roll files, see Natural under CICS and Natural under IMS TM in the Natural TP Monitor Interfaces documentation.
(Job I200, Step 0102)
This step is only required if you wish to use the Natural Roll Server.
Create and start the job ROLLSV1 before using
Natural.
For further information on the Natural Roll Server, see Natural Roll Server Operation in the Natural Operations documentation.
(Job I200, Step 0103)
This step is only required if you wish to use the Natural Authorized Services Manager.
Create and start the job AUTHSV1 before using
Natural.
For further information, see Authorized Services Manager in the Natural Operations documentation.
(Job I200, Steps 0108, 0109, 0115, 0120)
Sample Natural RPC server.
Step 0108, create the sample JCL to execute a Natural RPC server including the network task.
Step 0109, create the sample JCL to execute a Natural RPC server with TCP/IP task.
Step 0115, create the sample JCL to execute a standard Natural RPC server task without RPC server front-end.
Step 0120, create the sample JCL to execute a Natural RPC server task by the RPC server front-end. This JCL is necessary for impersonation.
If you want to use Natural RPC: Set
the parameters in the SMA group RPC accordingly; in particular,
set the parameter NAT-RPC to Y (Yes).
For further information, see Starting a Natural RPC Server and Starting a Batch Server in a Mainframe Environment in the Natural Remote Procedure Call (RPC) documentation.
For base Natural, there are no specific installation verification procedures.
After the last step of the installation procedure has been successfully performed, check that the following results are available:
Communication between Adabas and Natural is working.
The Natural system files have been loaded.
Batch Natural is operational.