Version 7.5.1

Installing Adabas Transaction Manager for OS/390, z/OS, and z/OS.e


The Installation Tape

Review the Report of Tape Creation that accompanies the release package before restoring the release data to disk.

The installation tape contains the following datasets in the sequence indicated in the report:

Dataset Contents
ATMvrs.JOBS Installation jobs, utility jobs
ATMvrs.LOAD Executable modules
ATMvrs.SYS5 ADALOD input for the ATM PRR file
ATMvrs.SYS6 ADALOD input for the ATM STJ file
ATMvrs.SYS7 ADALOD input for the user proxy log (UPL) file
ATMvrs.SYS8 ADALOD input for the ET data file
ATMvrs.INPL Online Services application
ATMvrs.ERRN Online Services messages
ATMvrs.SYSC ADALOD input for the Adabas System Coordinator file
ADA743.LX06 Adabas load library update

where vrs is the version, revision, and system maintenance level of the product. Use the comments in the jobs when modifying them to conform to site requirements.

Top of page

Installation Checklist

The steps needed for a successful installation are as follows:

Note:
The checklist and Installation Procedure indicate how to install a new ATM environment. If you need to upgrade an environment from an earlier version of ATM, refer to Upgrading from Earlier Versions of ATM for important additional information..

Step Description Job Name
  Before proceeding with the installation, ensure that all necessary preparation has been completed as described in section Before You Install.  
1 Restore the libraries from the installation tape.  
2 Create the transaction manager daemon database. ATMI030
3 Load the transaction manager files to the ATM daemon’s database. ATM1050
4 INPL the Online Services application. ATM1061
5 Define the default job parameters for use by the transaction manager proxy.  
6 Prepare the Adabas Transaction Manager daemon job. ATMI200
7 If required, define an Adabas System Coordinator file for migrated transaction records.  
8 Enable databases for two-phase commit.  
9 Prepare the Adabas System Coordinator daemons to support ATM.  
10 Make Adabas Transaction Manager components available as required.  

Top of page

Installation Procedure

Following is the general Adabas Transaction Manager installation procedure. The actual installation depends on your particular requirements and the specific contents of the release package provided by Software AG for your site. Information in the release package is intended for your system. If that information differs from the information in this section, use the release package information or contact Software AG technical support for assistance.

Step1: Copying the Tape Contents to Disk

If you are using System Maintenance Aid (SMA), refer to the SMA documentation (included on the current edition of the Natural documentation CD). If you are not using SMA, perform steps 1a, 1b and 1c as described in this section:

Note:
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.

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

The data set COPY.JOB (label 2) contains the JCL to unload all other existing data sets 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=<Tnnnnn>),
// LABEL=(2,SL)
//SYSUT2 DD DSN=<hilev>.COPY.JOB,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,VOL=SER=<vvvvvv>,
// SPACE=(TRK,(1,1),RLSE),
// DCB=*.SYSUT1
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
// 
where: 

<hilev>  is a valid high level qualifier 
<Tnnnnn> is the tape number 
<vvvvvv> is the desired volser  

Step 1b: Modify COPY.JOB

Modify the COPY.JOB to conform with your local naming conventions and set the disk space parameters before submitting this job:

Step 1c: Submit COPY.JOB

Submit COPY.JOB to unload all other data sets from the tape to your disk.

Step 2: Create the Transaction Manager Daemon Database (Job ATMI030)(SMA Job I030, Steps 4190,4191)

The transaction manager daemon database holds recovery information and, depending on the setting of the TMETDATA parameter, ET data, but no other operational data. The remaining files are for occasional use for special purposes – to store diagnostic log information obtained by the transaction manager proxy, and to hold details of transactions that were forcibly terminated. The size of this database depends mainly on the number of transactions that might be in progress at the same time, and the total amount of ET data, if any, that the ATM daemon will need to store.

Start of instruction setto create the daemon database:

Use the normal reporting utilities to determine whether space shortages are likely to occur.

Step 3: Load the Transaction Manager Files into the ATM Daemon’s Database (Job ATMI050)(SMA Job I050, Step 4190)

The recovery record file, suspect transaction file, proxy log file and ET data file have numbers 5, 6, 7 and 8, respectively. These file numbers are fixed. Since no application files should be loaded into this database, there should be no conflict.

If ET data is to be stored in the ATM daemon’s database (TMETDATA=ATM), define file 8 with MAXISN large enough to allow an ISN for each ETID that will ever be used in this Adabas Transaction Manager’s local system. A decompressed ET data record occupies about 2 kilobytes. If you choose to store ET data in target databases (TMETDATA=TARGETS), file 8 will not be used. For more information, see TMETDATA parameter.

Start of instruction setto load the Transaction Manager files into the ATM daemon’s database:

The suggested sizes are adequate for the purposes of testing. You can use the normal reporting utilities to check whether your system needs larger files.

Step 4: Install the Online Services Application SYSATM (Job ATMI061)(SMA Job I061, Steps 4190,4193)

The Adabas Transaction Manager Online Services application is delivered on the installation tape as a NATUNLD dataset created under Natural 3.1. The application programs are stored in libraries SYSATM and SYSMTvrs where vrs is the version, revision, and system maintenance level of the product.

Start of instruction setto install the Online Services application SYSATM:

  1. Use a Natural utility to install the Online Services application and ERRLODUS to install its messages.

  2. If Natural Security is installed, define the libraries SYSATM and SYSMTvrs, where vrs is the version, revision, and system maintenance level of the product.

Step 5: Define the Default Job Parameters for the Transaction Manager Proxy

The default job parameters for the Transaction Manager proxy must be defined. For further information, see Online Services, Job Parameters. See also the section Adabas Transaction Manager Components.

Note:
If you are upgrading from ATM version 7.4, you must modify each set of job parameters by providing a value for the Adabas System Coordinator Group Name.

Start of instruction setto define the default job parameters for the Transaction Manager proxy:

  1. Start a Natural session and log on to the newly installed SYSATM application. Invoke the Menu function. If you have not defined LFILE 152 for your Natural session, a message will prompt you to define it now. Select Systems Settings, then option LFILE 152 Maintenance. Enter the Database ID and file number of the system file that you created when you installed the Adabas System Coordinator. Enter values for the remaining input fields, and confirm your definition. Now return to the main menu and select the Job Parameters option. For a detailed description of the following step, refer to Online Services, Job Parameters.

  2. On the Job Parameters screen, press PF10 to add a new default definition. Make sure that you set Adabas Transaction Manager to ON. Confirm your new definition, then select it for modification by marking it with an “m”. Set the SVC number that will be used by the Adabas Transaction Manager daemon that you are installing. You must also set the name of the Adabas System Coordinator group in which your client jobs and TP systems will execute. The provided default values for the remaining parameters should be satisfactory for the purpose of completing and verifying the installation. You can review and change them as required once you have completed and verified the installation.

Step 6: Prepare the Adabas Transaction Manager Daemon Job (SMA Job I200, Step 4190)

Because the Adabas Transaction Manager daemon executes as a special kind of Adabas nucleus, its JCL is similar to that of a normal Adabas nucleus.

Start of instruction setto prepare the Adabas Transaction Manager daemon job:

  1. Make any necessary site-specific changes to ATMI200 so that it can be used as a procedure for a started task.

  2. Ensure that any ADALNK module that can be loaded by the ATM job does not have the Adabas System Coordinator stub linked into it.

  3. Specify ADARUN DTP=TM.

  4. Specify ADARUN TMLOG=NEVER for the purpose of verifying the installation. Once the verification process has been completed, reconsider this parameter setting.

  5. Specify ADARUN NONDES=YES. This is the default setting.

Set other ADARUN parameters as you would for a normal database. For initial testing, the default limits and pool and buffer sizes should be sufficient. You can use the sample parameters in the JOBS library, member TMPARMS, as a basis for the daemon’s ADARUN parameters.

See the section Parameters for a description of the ADARUN parameters that affect Adabas Transaction Manager operation.

Note:
An Adabas Transaction Manager daemon job must be run in each operating system image that will participate in distributed transaction processing (DTP). If more than one Adabas SVC is used in the same system image, an Adabas Transaction Manager daemon must be run under each Adabas SVC that will participate in DTP.

Step 7: Define an Adabas System Coordinator File

If you plan to use ATM in a multi-system dynamic transaction routing (DTR) environment, you might first need to define an Adabas System Coordinator file (SYSCO file) to hold migrated transaction records (MTRs) for the ATM daemons that will execute alongside the Adabas System Coordinator daemons in the group. This file is needed if you plan to use a multi-system DTR environment in which a user who is not at global transaction status can be migrated from one system image to another (for example, a CICSplex cluster with the ATM job parameter TRANMODE=DYNAMIC).

Note:
It is planned to provide a description of how to define and create a SYSCO file in the Adabas System Coordinator documentation. Until this description is available, please use the following instructions.

Start of instruction setto define a SYSCO file to contain migrated transaction records:

  1. Define a standard Adabas file to contain MTRs. For the Adabas Transaction Manager daemons in a COR group, a single MTR will be stored for each global transaction whose owner is migrated from one system image to another while the transaction is open; the record will be deleted when the transaction is finally committed or backed out. The following ADALOD parameters should be sufficient for 1000 MTRs at the same time, assuming block sizes of about 4 kilobytes for Data Storage and about 2 kilobytes for Associator:

    DSSIZE=50B
    NISIZE=30B
    UISIZE=5B

    During normal use, you can use the standard Adabas reporting utility to check that your file is of adequate size.

    An ADALOD input file is supplied on the installation tape. Load the empty file into a database which runs with high availability and which is accessible to all SYSCO daemons in the group.

  2. Log on to the online system, SYSCOR, of the Adabas System Coordinator. You will need a System Coordinator group definition for the group in which your ATM daemon will execute. Refer to the Adabas System Coordinator documentation for details of making group definitions. Having made your group definition, mark the group name with ‘F’, as shown below, and press Enter:

    07:53:01 ***** A D A B A S   SYSTEM COORDINATOR 7.4.2 (I005) *****  2005-01-19
                       -  System Coordinator Groups -                    C11200M1
    
    
    Runmode: Local                                               Session: Local
    
                                       Cluster Facility
    C Group Name   Type     SVC ID           Name          Members
    F  CORATMGP   Sysplex     254      CASPLI_CACHE1          1
       CORGROUP   Multi       244                             1    
    
    
    
    
    Mark with D(isplay),M(odify),P(urge),R(ename),E(xpand),F(iles)
    
    
     Command ==>
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12
          Help        Exit  Refr                                Add         Menu

    At the next screen, press PF10 to add a new definition. Enter the MTR file definition in the pop-up window, as follows, specifying a DBID and file number that are suitable for your installation:

    07:57:00                  Add File Definition              2005-01-19 
                                                                C11270M2
              
    
    Group Name: CORATMGP
    
     File Name: ATMMTR     DB ID: 135     File Number: 175    SVC: 254
    
    Description: ATM MIGRATED TRAN RECORDS
    
    
     
        Press PF5 to confirm 
    
    
    Command ==>
                           PF1 Help     PF3 Exit     PF5 Add 

    ATM’s MTR file must be defined with SYSCO file name ATMMTR.

    Note:
    If you do not create a definition for the MTR file using SYSCOR, ATM will assume that you have determined that no MTR file is needed. Even so, an ATM daemon might issue a warning message if it finds no definition. If this happens, and you are sure that you do not need an MTR file, you can prevent the message from appearing simply by creating a dummy MTR file definition for the COR group, using SYSCOR.

Step 8: Enable Databases for Two-Phase Commit Processing

Start of instruction setto enable databases for two-phase commit processing

  1. Ensure that the parameter

    ADARUN DTP=RM

    is set in every database that participates in global transactions coordinated by Adabas Transaction Manager.

  2. Add the Adabas System Coordinator load library and the Adabas Transaction Manager load library to the STEPLIB DD concatenation.

  3. In the case of Adabas Cluster Services or Adabas Parallel Services databases, use the Adabas 7.4 update library LX06, concatenated before the standard Adabas 7.4.3 library in the STEPLIB concatenation.

  4. In the case of Adabas 7.1 databases, you must apply fix A$71306 to your Adabas 7.1 load library. The fix is contained in member ZAPOPT of the supplied JOBS library.

    Caution:
    Applying this fix will make your Adabas 7.1 load library incompatible with Adabas Transaction Manager 1.2.

    Refer to the Adabas System Coordinator documentation for more information on how to run Adabas Transaction Manager 7.4 with Adabas 7.1 databases. The same instructions can be used for running Adabas Transaction Manager 7.5 with Adabas 7.1 databases.

Step 9: Prepare the Adabas System Coordinator Daemons

The ATM load library should be made available to all SYSCO daemons which will run under the same Adabas SVC as an ATM v7.5 daemon.

The SYSCO daemons must be started with the parameter setting PRODUCT=ATM.

Step 10: Make Adabas Transaction Manager Components Available

The ATM load library should be made available:

Ensure that the Adabas System Coordinator stub has been linked into the Adabas link modules that will be executed in each of the above environments.

The ATM load library and the Adabas System Coordinator library should be made available:

Caution:
The Adabas Transaction Manager proxy must not be used by any job or started task that executes an Adabas Transaction Manager daemon, an Entire Net-Work node, or an Adabas nucleus running in multiuser mode. You should therefore make sure that the Adabas System Coordinator stub is not present in any ADALNK module that might be used by these jobs.

Top of page