Installation Procedure for z/OS

Important Information

The Software AG Installer (download center) has limited support for z/OS at present. However, the installation (and activation) of the z/OS software is downloaded along with all other platforms. Here are some useful points to help you understand the process overall:

  • The install image must be downloaded to one of the other supported platforms (Windows or UNIX for example).

  • There is a special z/OS activation step that has to run in this download platform. This activation step FTPs the z/OS software from the download platform into the z/OS system.


Data Archiving for Adabas is a fully portable technology. It runs in all primary UNIX systems, Windows and z/OS and has only one code-base.

IBM’s z/OS has embedded UNIX System Services (USS) within it. This is part of the ongoing modernization that has been happening to the operating system in recent years. This means z/OS is able to embrace modern technologies that in the past were considered only for off-host (outside the mainframe).

Data Archiving for Adabas runs within a USS process within z/OS accessing normal z/OS Adabas databases.

Actions Required Before Starting the Install

During the install you must identify the database and file number for the Repository. Please refer to the section Installation Planning and Preparation for information on how to manage that part of the installation.

Before the installation you must:

Create Data Set for ADR Load Library

The ADR install requires that you construct a load library with the following specific attributes:


Example dataset name: SAG.ADRvrs.LOAD, where vrs is the product version.

Create Site-Based Adabas Link Routine (ADALNKR)

Make a site-based ADALNKR with the appropriate SVC number for your site. Make it available in the z/OS dataset mentioned above. LNKGBLS must be linked in with your ADALNKR in this library.

Make sure ADALNKR is fully maintained.

Here is some example JCL…

//LNKRGBLS JOB CLASS=G,MSGCLASS=X                                   
//* ----------------------------------------------------------------- * 
//* Assemble LNKGBLS - reentrant                                    - * 
//* ----------------------------------------------------------------- * 
//GBLSWLS EXEC ASMACL,                                                  
//      PARM.C='ASA,NODECK,OBJECT,XREF(SHORT),TERM',                    
//      PARM.L='XREF,LIST(ALL),LET,MAP,NCAL'                            
//C.SYSLIB     DD DISP=SHR,DSN=SAG.ADAvrs.SRCE                       
//             DD DSN=SYS1.MACLIB,DISP=SHR                              
//             DD DSN=SYS1.MODGEN,DISP=SHR                              
//C.SYSPRINT   DD SYSOUT=*                                              
//C.SYSTERM    DD SYSOUT=*                                              
//C.SYSIN      DD *                                                     
*        Global definitions for the Adabas link routine          
*        for Batch/TSO.                                                 
*        Modify this sample for your site.
*        Then assemble and link it and include the       
*        resulting module with ADALNK8 to create the ADALNKR
*        for use with ADR in z/OS.          
         LGBLSET LOGID=1,         DEFAULT ADABAS DBID                  X
               SVCNO=252,         DEFAULT ADABAS SVC NUMBER            X
               OPSYS=ZOS,         Operating system                     X
               COR=NO,            Activate System Coordinator          X
               TPMON=BAT,         Batch/TSO                            X
               RENT=YES,          Non-reentrant for Batch/TSO          X
               GEN=CSECT,         Generate CSECT for load module       X
               USERX1=NO,         Link user exit 1 YES/NO              X
               LX1NAME=UEXITB,    User exit 1 module name              X
               USERX2=NO,         Link user exit 2 YES/NO              X
               LX2NAME=UEXITA,    User exit 2 module name              X
               UES=YES            Enable UES                            
//L.SYSPRINT   DD SYSOUT=*                                              
//L.SYSIN   DD  *                                                       
 MODE AMODE(31),RMODE(ANY)                                              
 ENTRY LNKGBLS                 Default entry name                       
 NAME LNKGBLS(R)               DEFAULT TABLE NAME                       
//* ----------------------------------------------------------------- * 
//* LINK ADALNKR with LNKGBLS                                       - * 
//* ----------------------------------------------------------------- * 
//LINKA8Y EXEC PGM=IEWL,                                                
//      PARM='LET,LIST(ALL),MAP,XREF,REUS=RENT',REGION=4M               
//SYSPRINT     DD  SYSOUT=*                                             
//SYSUT1       DD  DSN=&&SYSUT1,SPACE=(1024,(120,120),,,ROUND),UNIT=VIO 
//ADALIB       DD  DISP=SHR,DSN=SAG.ADAvrs.LOAD                      
//SYSLIN       DD  *                                                    
  MODE AMODE(31),RMODE(ANY)                                             
  INCLUDE ADALIB(ADALNKR8)              /* V8 LINK ROUTINE */           
  INCLUDE SYSLMOD(LNKGBLS)                                              
  INCLUDE ADALIB(LNKUES)                                                
  INCLUDE ADALIB(ASC2EBC)                                               
  INCLUDE ADALIB(EBC2ASC)                                               
  ENTRY ADABAS                                                          
  NAME ADALNKR(R)                                                       

Some Useful Information about USS (OMVS)

Activating OMVS (USS: UNIX System Services) in z/OS

OMVS is usually available within z/OS by default because many other software components from other vendors (including IBM) use it. If it is not available, you can use the following information to make it available:

  • When z/OS is first installed and configured a RACF (or equivalent) basic user called IBMUSER is defined. The IBMUSER is automatically defined with an OMVS segment. It is an OMVS segment that enables a user to use OMVS (USS).

  • Therefore, your RACF or equivalent systems such as ACF2, TOP SECRET etc. (please consult the appropriate documentation of these other systems for similar information) administrator needs to add an OMVS segment to all users who are to use OMVS, including the person who will be doing the ADR install.

  • An OMVS segment contains the following:

    • UID.

      A numeric UID like in any other UNIX system. This UID represents one sharable UNIX that one or more userids may be able to use. There may be many more OMVS systems (UID) defined for your system.

    • Home directory.

      Something like /u/nat/xyz

    • A shell program.

      This is essentially UNIX (the korn shell), often called “ksh” in the UNIX community. An example of this may be: /bin/sh

    • Maximum size.

      This is akin to address-space size. It may be allowed to default. It is not unusual for a UNIX OMVS to be 128-512 meg.

  • In RACF the command to add such a segment would be…

    ALU <userid>  OMVS (UID(1234) HOME ('/u/nat/xyz') PROGRAM ('/bin/sh') 

    This command needs to be entered using a tool that supports mixed case (such as TSO ISPF/PDF/Option 6).

  • Next, a UNIX group should be assigned to the <userid>. Again, this is a numeric and is referred to as "GID". A normal RACF "connect" command can be used to do this.

    A GID can be assigned to a RACF group with…

    ALG <group> OMVS(GID(nn))
  • The home directory needs to be created in the filesystem (HFS, ZFS etc).

Getting into OMVS via TSO

Once the permissions, home directory etc. are acquired, there are two typical ways to get into OMVS. One is through TSO. Get into TSO and issue the OMVS command and press Enter.



Getting into OMVS via Telnet

You can get to OMVS like any other UNIX system from outside z/OS using telnet. Enter the following at your workstation:

telnet <computer> <port>

This will enable access into the OMVS UNIX at the same point as entering “OMVS” in TSO.

Entering UNIX Commands

Once in OMVS, you will be able to use all the usual UNIX directives:

Directive Description
cd Change directory
mkdir Make directory
chmod Set protection
chown Set owner
chgrp Change group
ls -la Display directory contents

Installation Preparation Checklist

There are a number of things that need to be done prior to installing. These have been covered in the preceding sections and are summarized here as a checklist to help you ensure the installation is successful:

Step Description Notes

Check the system name and hostname of the z/OS machine where the software is being installed:

  • the system name and hostname must be the same

  • the hostname must resolve to the correct IP address

Use the uname command to acquire the system name:

da3f:saguser> uname –a
OS/390 DA3F 20.00 03 2098

Use the onslookup command with the system name to acquire the hostname and IP address:

da3f:saguser> onslookup DA3F
Defaulting to nslookup version 4
Starting nslookup version 4

Name:    DA3F.hq.sag

Check the amount of free disk space available in the directory in the USS filesystem where the software is being installed.

Minimum disk space: 300 MB

Use the df command to see the amount of free space available:

da3f:saguser> df –k /opt/softwareag


Check the amount of memory (region size) available to a process running in the USS environment.

If you use OMVS from TSO, the amount of memory available in USS is governed by region size of the TSO session.

The region size of the TSO session is configured via the SIZE attribute in the TSO segment of the user's RACF profile.

Minimum memory: 64 MB

Minimum memory: 64 MB


User ID and password for the USS account that will be used to install and run the software.

Make sure that the account has read/write and execute permissions to the installation directory in the USS filesystem (from Step 2 above).

User ID: saguser
Password: ********

Check that the USS account (from Step 4 above) has the correct z/OS security permissions for the dataset where the ADALNKR/LNKGBLS were prepared earlier.

The load library dataset must not be in use by any other process.

Dataset: SAG.ADRvrl.LOAD

Adabas database and file number for the Repository.

This can be a file that will be created or replaced as part of the installation, or it can be an existing file shared by another computer already running Data Archiving for Adabas.

If the file is being shared by another computer, the hostname of the computer and its Group Services port number will be required (default 53376).

Database: 10
File number: 120

Choose one of:

  • create

  • replace

  • share

When choosing share you will be prompted for:

Hostname: sunpcc10.hq.sag
Portnumber: 53376

Download location. This is the non-z/OS computer where you either download directly or placed the software distribution image.

Installations are much faster if you use a local disk on the download computer.



Details for the FTP upload of the z/OS software because the software must be uploaded to z/OS. The following information is needed:

  • Hostname of z/OS (from 1 above)

  • User ID (from 4 above)

  • Password (from 4 above)

  • Temporary target upload directory

Software AG recommends the target directory for the upload is different to the location where the software will finally be installed, since the FTP is only a temporary step. Typically, this is a temporary directory in the user’s home directory.

Check the amount of free disk space available in the target directory.

Minimum upload disk space: 30MB

Hostname: da3f.hq.sag
User ID: saguser
Password: ********
Directory: /u/saguser/tmp

The df command shows the amount of free space available:

da3f:saguser> df –k /u/saguser/tmp


The components of Data Archiving for Adabas are installed using the Software AG Installer from the Software AG download center. Please refer to the Data Archiving for Adabas Software AG Installer section Component Installation for information on how to perform this part of the installation.


Once the Software AG Installer has prepared the install download image, or you have copied the download install image to the computer where the activation will be performed, you must now perform the z/OS activation. For information on how to start the activation on your chosen off-host platform (Windows or UNIX), refer to Starting the Activation in the Activation section of the Installation Procedure for Windows and UNIX.

Windows Server editions may require that you disable the windows firewall to perform the z/OS FTP install. This is because popup notifications are disabled by default so you do not get the dialog asking if you want to allow activation network access that you would see on other Windows platforms.

Once you start the activation process, you are required to progress through a number of activation tabs:


The first tab in the activation requires that you select the platform that you are activating and the products too. Select z/OS as the platform and COR and ADR as the products:


COR (Adabas System Coordinator)

The COR tab requires you to provide information about port numbers, computer names and Repository location.

The following screenshot shows an example of the COR tab:


Field Description
Group Services Port

System Coordinator uses ports for communication between components. This setting defines the port number to be used for communicating with the System Coordinator daemon residing on the computer defined in the “Computer hostname / IP address” field below.

Normally the default setting is used.

Dynamic Port Range start/end

System Coordinator also uses dynamic ports for communication between components.

Normally the default settings are used.

Override default computer node name

Sometimes a machine is configured in such a way that the automatically detected computer hostname does not match the one that needs to be used (e.g. multiple network interfaces or multiple IP stacks). In this case you can override the detected computer hostname with a user defined hostname or IP address to be used at runtime. To do this, select the checkbox and enter the value to be used in the (now enabled) “Computer hostname / IP address” field.

Computer hostname / IP address

This is the automatically detected hostname. This is display only unless the “Override default computer node name” checkbox has been selected in which case it can be overridden. The “Group Services Port” number defined above is used to communicate to the System Coordinator daemon residing on the computer name shown here.

Repository Location  
Computer Hostname

This is the computer hostname where the Repository is already located or, if this is the first installation, where the Repository is to be located (in which case it should be defined to be the local computer hostname).

Group Services Port

This setting defines the port number to be used for communicating with the System Coordinator daemon residing on the computer defined in the “Computer hostname” field above.

Adabas database / file

This is the database and file number of the Repository.

The database must exist and be active in order for the activation to be successful. If the file already exists it will be used, if not, it will be automatically created.

Continue activation even if this daemon is not active

By default, when leaving this COR tab, a connection check will be performed using the above Repository location “Computer hostname” and “Group Services Port”.

When this option is selected, the connection check is not done, enabling the activation to continue without the System Coordinator daemon (residing on the“Computer hostname” and “Group Services Port” defined above), used to access the Repository, being active.

Dataset where prepared ADALNKR (etc) resides

You must identify the z/OS dataset where you previously created your site-based Adabas link routine ADALNKR earlier. Refer to Create Data Set for ADR Load Library.

JCL (for dynamic activation submission)

You must edit the model JCL so that it is valid for your site, but do not modify the <USER_PLACEHOLDER> or <COMMAND_PLACEHOLDER> because this is dynamically replaced at runtime.

ADR (Data Archiving for Adabas)

The ADR tab requires you to adjust the dynamic submission JCL to run correctly at your site, but do not modify the <USER_PLACEHOLDER> or <COMMAND_PLACEHOLDER> because this is dynamically replaced at runtime.

The following screenshot shows an example of the ADR tab:


FTP Parameters

TThe FTP Parameters tab requires you to define your FTP information:

The following screenshot shows an example of the FTP Parameters tab:


Field Description

This is the name of the z/OS system where the activation is to take place.


This is the z/OS FTP port number, usually 21.


This is the z/OS logon id for RACF, ACF2, or TOP Secret (as appropriate) to be used.


This is the password corresponding to the logon id specified for ‘User’ above.


Here you can (optionally) specify any extra commands that your FTP server configuration may require. For example, you may need to stop automatic translation by specifying your systems encodings e.g. “ENCODING=SBCS SBDATACONN (IBM-1047, IBM-1252)“. In most cases this is not required.

FTP Target Directory

The directory location where you wish to initially load the install files.

This is an intermediate destination. The final installation location is determined by the Installation Directory below.

JCL Temporary dataset

A temporary z/OS dataset is required to dynamically construct the activation JCL. This must be a file that the logon id specified for ‘User’ above has modify permissions.

Installation Directory

The final location where the software will reside and run from.

Test FTP Settings

This button will perform only basic checking of the information supplied.


Once all options have been selected the next thing to do is to select the activate tab so the activation log screen appears. Start the activation by clicking the Activate button below.


The activation log screen shows progress during execution which may contain important information if a problem occurs (such as permissions failure). Here is a successful activation execution completion:


Workload Management

This section describes the default job name prefixes used for the various components of Data Archiving for Adabas and Adabas System Coordinator. This information may be useful for controlling the processing resources of these jobs.

The _BPX_JOBNAME environment variable is used to control the job name prefix used for the Data Archiving for Adabas and Adabas System Coordinator tasks. By default, the job name prefix will be set to match the program name.

For Adabas System Coordinator:

Launch Control: CORLC*
Daemon: CORD*

For Data Archiving for Adabas:

Extractor/Accumulator: ADRDRV*

The job name prefix can be changed by setting the _BPX_JOBNAME environment variable in the UNIX System Services environment before starting Adabas System Coordinator, for example by modifying the $SAG/cor/v826/INSTALL/corenv script to include the following lines:

  export _BPX_JOBNAME

This will set the job name prefix for all the above tasks (Launch Control, Daemon and Extractor/Accumulator) to ABC*.

When starting Adabas System Coordinator in batch, the JCL can set the _BPX_JOBNAME environment variable in the PARM= parameter or STDENV DD card statement:

PARM= example:

//COR826 JOB CLASS=K,MSGCLASS=X                                           
//RUNCOR EXEC PGM=BPXBATCH,REGION=0M,                                  
//       PARM=('pgm /opt/softwareag/sag/cor/v826/INSTALL/ start' 'ENVAR("_BPX_JOBNAME=ABC"'))  
//STDOUT DD PATH='/opt/softwareag/sag/cor/v826/bin/stdout',           
// PATHOPTS=(OCREAT,OAPPEND,OWRONLY),                                  
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH)                              
//STDERR DD PATH='/opt/softwareag/sag/cor/v826/bin/stderr',           
// PATHOPTS=(OCREAT,OAPPEND,OWRONLY),                                  
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH)                              
//STDIN  DD PATH='/dev/null',                                          
// PATHOPTS=(ORDONLY)                                                  
//STDENV DD *                                                          

STDENV example:

//COR826 JOB CLASS=K,MSGCLASS=X                                           
//RUNCOR EXEC PGM=BPXBATCH,REGION=0M,                                  
//       PARM=('pgm /opt/softwareag/sag/cor/v826/INSTALL/ start')  
//STDOUT DD PATH='/opt/softwareag/sag/cor/v826/bin/stdout',           
// PATHOPTS=(OCREAT,OAPPEND,OWRONLY),                                  
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH)                              
//STDERR DD PATH='/opt/softwareag/sag/cor/v826/bin/stderr',           
// PATHOPTS=(OCREAT,OAPPEND,OWRONLY),                                  
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH)                              
//STDIN  DD PATH='/dev/null',                                          
// PATHOPTS=(ORDONLY)                                                  
//STDENV DD *                                                          


Data Archiving for Adabas is administered using Software AG's cross-product and cross-platform product management framework System Management Hub (SMH).

In order to do this, the Administration component of Data Archiving for Adabas must be installed on a Windows or UNIX machine (this does not have to be the same machine which performed the z/OS activation).

Refer to Installation Procedure for Windows and UNIX for instructions on how to perform the Administration component installation. At the end of this installation process, the section Starting to Use the Software describes how to sign on to the System Management Hub and check that the installation is complete.

You can now begin using Data Archiving for Adabas. See the section Getting Started for further information.