Installation

This section describes the steps needed to install the Adabas System Coordinator Versioning Tool.

• Objects

• Overview

• Before You Start

• Client Versioning (Batch)

• Client Versioning (CICS)

• Database Versioning

• Daemon Versioning

• Final Steps

• Installation Controls

• Control Descriptions

• Installation Verification

Objects

The Versioning Tool objects (load modules, macros and sample jobs) are all supplied with Adabas System Coordinator. All objects have the name prefix "VER".

Overview

The steps needed for a successful installation of the Versioning Tool are as follows:

Before You Start

Before you start, versioning load libraries need to be created.

• Load library for Versioning

• Additional load library for Client Versioning

Load library for Versioning

Software AG recommends that versioning is implemented by creating a new library to hold copies of product modules that have been renamed in support of versioning. This will protect the original modules. It will also enable new maintenance to be applied to the original modules, which can then be refreshed in the versioning libraries by re-running the appropriate installation jobs.

This library is referred to as the ALLVERS Versioning Library and, in the sample job control supplied, is named SAG.CORVER.ALLVERS.LOAD.

The library is added to the Joblib or Steplib concatenation of all Adabas databases, client application jobs (for example, batch jobs, TSO CLISTs, CICS jobs), batch Adabas server start-up jobs and Coordinator daemon tasks that require versioning support.

Additional load library for Client Versioning

If you are implementing Client Versioning, you need to create a second library that will be used for the special link modules (VERLNK01, VERCIC01, ADALNKnn, ADABASnn), and the client versioning tables. This library is referred to as the Client Versioning Library and, in the sample job control supplied, is named SAG.CORVER.CLIENT.LOAD.

Note:
It is imperative that these link modules are only used in the client environment. Therefore, they must not be placed in the ALLVERS Versioning Library that is used by the Adabas databases and System Coordinator or SAF Security daemons.

Client Versioning (Batch)

• Create the Batch versioning table (Job I065)

• Copy the client versioning modules to the Client Versioning Library (Job I085)

• (Optional) Zap the Batch versioning link module defaults (Job I088)

• Copy required link modules to the Client Versioning Library

Create the Batch versioning table (Job I065)

Use sample job VERI065 to assemble and link the Batch versioning table, VERC01 (standard) or VERC09 (re-entrant).

Note:
The versioning table load modules must be linked REUS, and not RENT.

Using the VERCL macro, the client versioning table for Batch clients can be created. Here is an example:

* ------------------------------------------------- 
* Default controls for Batch client versioning
* ------------------------------------------------- 
         VERCL JOBTYPE=BATCH,  Batch clients
               OVERIDES=YES,
               WTO=NO,
               LNKGBLXX=YES,
               BINDGBLS=IGNORED,
               DBID=DDCARD,
               SVC=DDCARD
* ------------------------------------------------- 
* >>> Versioned Link Module Entry
* ------------------------------------------------- 
         VERCL VRL=823,        Version 8.2.3
               DEFAULT=YES,    Default link module
               SUFFIX=82
* ------------------------------------------------- 
* >>> Versioned Link Module Entry
* ------------------------------------------------- 
         VERCL VRL=814,        Version 8.1.4
               SUFFIX=81,
               DBID=15,
               SVC=ASIS
* ------------------------------------------------- 
* >>>>>> Specific Jobname Entry
* ------------------------------------------------- 
         VERCL JOBNAME=jobname, Uses Version 8.1.4
               DBID=15,
               SVC=ASIS
* ------------------------------------------------- 
         VERCL TYPE=END        End of Controls

The (mandatory) first element introduces default controls for (a) general Batch client versioning and (b) Versioned Link Module Entries.

Following the mandatory first element are elements which identify the versioned link module(s) to be used – these are referred to as Versioned Link Module Entries. At least one entry must be defined and one of those entries must be defined to be the default link module. In the example above, the version 8.2.3 link module identified by a suffix of 82 has been defined to be the default link module.

Versioned Link Module Entries which are not defined as the default link module are each followed by one or more Specific Jobname Entries which comprise of a list of job names that will use the versioned link module that precedes them. In the example above jobname will use the version 8.1.4 link module identified by a suffix of 81.

If a job name is not matched (at runtime) with an entry in the versioning table then it will use the default link module. In the example above, this would be the version 8.2.3 link module identified by a suffix of 82.

Versioned Link Module Entries can optionally choose to override the default controls defined by the mandatory first element but only if OVERIDES=YES has been specified (as in the example above).

Refer to Client Versioning Controls (Batch) for an explanation of the VERCL controls.

Copy the client versioning modules to the Client Versioning Library (Job I085)

Use sample job VERI085 to copy the supplied load module VERLNK01 to your Client Versioning Library (see "Additional Load library for Client Versioning") as ADALNK and the supplied load module VERLNR01 as ADALNKR (making sure the real ADALNK and ADALNKR are not lost).

Important:
This Client Versioning Library must not be made available to any target in the Software AG network which acts as a DBID – such as Adabas, Broker, Com-Plete, Entire System Server, Net-Work, System Coordinator daemon etc.

(Optional) Zap the Batch versioning link module defaults (Job I088)

Certain fixed offsets in the Adabas link module contain information which is required by some callers of ADALNK, for example, the length of the USER and REVIEW extensions.

If you use other than default values, you must zap the correct values into the ADALNK and ADALNKR copies of VERLNK01 and VERLNR01. Sample job VERI088 may be used to do this.

Copy required link modules to the Client Versioning Library

Copy your existing ADALNK and LNKGBLS modules to the Client Versioning Library, renaming them to have the appropriate suffix:

ADALNKxx / LNKGBLxx for standard batch.

ADALNRxx / LNRGBLxx for re-entrant batch.

Client Versioning (CICS)

• Prepare CICS clients

• Create the CICS versioning table (Job I065)

• Link-edit VERCIC01 into the Client Versioning Library (Job I085)

• Copy required link modules to the Client Versioning Library

Prepare CICS clients

There are several prerequisites which must be fulfilled before you can use the CICS client versioning facility:

• Ensure that PARMTYP=ALL is set in LGBLSET (this is the default).

• PPT entries must be defined and installed for the following:

  • The Adabas client versioning link module (ADABAS, or other name you may choose). This must be specified as Resident.

  • The assembled CICS versioning table VERC03. This must be specified as Resident.

  • All renamed Adabas CICS link modules, Adabas TRUEs and Adabas PLT programs (LNKENAB and ADACIC0).

  • All renamed Add-on product modules (if they currently have PPT entries defined for them).

Create the CICS versioning table (Job I065)

Use sample job VERI065 to assemble and link the CICS versioning table, VERC03.

Using the VERCL macro, the client versioning table for CICS clients can be created. Here is an example:

* ------------------------------------------------- 
* Default controls for CICS client versioning
* ------------------------------------------------- 
         VERCL JOBTYPE=CICS,   CICS clients
            COFF=0,
            WTO=NO
* ------------------------------------------------- 
* >>> Versioned Link Module Entry
* ------------------------------------------------- 
         VERCL VRL=823,        Version 8.2.3
            DEFAULT=YES,    Default link module
            SUFFIX=82
* ------------------------------------------------- 
* >>> Versioned Link Module Entry
* ------------------------------------------------- 
         VERCL VRL=814,        Version 8.1.4
            SUFFIX=81
* ------------------------------------------------- 
* >>>>>> Specific Transaction-ID Entry
* ------------------------------------------------- 
            VERCL TRAN=AA82       Uses Version 8.1.4
* ------------------------------------------------- 
      VERCL TYPE=END        End of Controls

The (mandatory) first element introduces default controls for general CICS client versioning.

Following the mandatory first element are elements which identify the versioned link module(s) to be used – these are referred to as Versioned Link Module Entries. At least one entry must be defined and one of those entries must be defined to be the default link module. In the example above, the version 8.2.3 link module identified by a suffix of 82 has been defined to be the default link module.

Versioned Link Module Entries which are not defined as the default link module are each followed by one or more Specific Transaction-ID Entries which comprise of a list of transaction-IDs that will use the versioned link module that precedes them. In the example above transaction-ID AA82 will use the version 8.1.4 link module identified by a suffix of 81.

If a Transaction-ID is not matched (at runtime) with an entry in the versioning table then it will use the default link module. In the example above, this would be the version 8.2.3 link module identified by a suffix of 82.

Refer to Client Versioning Controls (CICS) for an explanation of the VERCL controls.

Link-edit VERCIC01 into the Client Versioning Library (Job I085)

Use sample job VERI085 to link the supplied load module VERCIC01 with your CICS stubs, naming the output load module appropriately (for example ADABAS).

Copy required link modules to the Client Versioning Library

For each suffix defined in the CICS versioning table, you will need modules named as follows:

where xx is the suffix and the first 6 characters of the module name must be as shown above.

Sample steps to create a set of versioning modules with suffix 82:

MACIOPT ENTRY=GLOBAL,MNTRUE=8
      MACIOPT ENTRY=GROUP,GTNAME=CICGBL82
      MACIOPT ENTRY=FINAL
      END

MACINS TRUENAME=ADATRU82,GTNAME=CICGBL82 
      END

GBLNAME=CICGBL82,
      ENTPT=ADABAS,
      TRUENM=ADATRU82,

MODE AMODE(31),RMODE(ANY)
     INCLUDE ACILIB(ADACIC0)
     INCLUDE USERLIB(ACIOPT82)
     ENTRY ADACIC0
     NAME ADAENA82(R)

MODE AMODE(31),RMODE(ANY)
     REPLACE ACINAMES
     INCLUDE ACILIB(ADACICS)
     INCLUDE USERLIB(ACINAM82)
     ENTRY ADACICS
     NAME ADABAS82(R)

MODE AMODE(31),RMODE(ANY)
     INCLUDE  ACILIB(ADACICT)
     ENTRY ADACICT
     NAME ADATRU82(R)

Notes:

1. 1. The CICS versioning tool supports callers using both the Direct Call Interface and the EXEC CICS LINK interface. It always uses the DCI to call the various Adabas link modules.
2. 2. When invoked via EXEC CICS LINK, it first looks for the Adabas parameter list in COMMAREA and then in TWA.
3. 3. Do not use CICS NEWCOPY to reload the versioning tool, versioning table or any Adabas link modules defined in the versioning table.
4. 4. If you use the Adabas System Coordinator Node Error Program, you must be sure to change the sample source so that it starts the CORNEP transaction for each link module.

Database Versioning

Use sample job VERI055 to assemble the database versioning table, VERDBT.

Using the VERDB macro, the database versioning table will have an entry for each installed version of the Add-on products. Here is an example:

VERDB SUFFIX=81,VRL=812
VERDB SUFFIX=82,VRL=822
VERDB SUFFIX=xx,VRL=vrs
VERDB TYPE=END

The following rules apply:

• The values for SUFFIX= are unique across all VERDB entries in the table.

• The values for VRL= are unique across all VERDB entries in the table.

• The table must end with VERDB TYPE=END.

Refer to Database Versioning Controls for an explanation of the VERDB controls.

Daemon Versioning

Use sample job VERI060 to assemble the daemon versioning table, VERDMT.

Note:
This is an optional activity. You may still run the Adabas System Coordinator and/or Adabas SAF Security daemon from the original product libraries, if desired.

Using the VERDM macro, the daemon versioning table will have an entry for each daemon and its corresponding suffix and version. Here is an example:

VERDM SUFFIX=81,VRL=812,JOBNAME=SYSCO812
VERDM SUFFIX=82,VRL=822,JOBNAME=SYSCO822
VERDM SUFFIX=82,VRL=822,JOBNAME=SAFDAEMN
VERDM SUFFIX=xx,VRL=vrs,JOBNAME=daemon-name
VERDM TYPE=END

Refer to Daemon Versioning Controls for an explanation of the VERDM controls.

Final Steps

• Copy and rename required product modules into the ALLVERS Versioning Library

• Add the Versioning Libraries to required Job Control

Copy and rename required product modules into the ALLVERS Versioning Library

Refer to the sample jobs VERI080* to identify and customize the one relevant to the version whose modules you wish to copy.

The sample jobs indicate all of the modules that require copying and renaming. No other product modules should be renamed.

Add the Versioning Libraries to required Job Control

The ALLVERS Versioning Library must be added to the Joblib or Steplib concatenation of all Adabas database start-up jobs that require versioning support. The library should be added at the top of the concatenation.

If you want to run the System Coordinator or SAF Security daemon from the same versioning load library, you should also add the ALLVERS Versioning Library first in the daemon Joblib or Steplib concatenation.

The ALLVERS Versioning Library and the Client Versioning Library must be added to the top of the Steplib concatenation for any batch jobs that require versioning support.

For CICS, the Client Versioning Library and the ALLVERS Versioning Library must be added to the DFHRPL and Steplib concatenations.

Installation Controls

The Versioning Tool operation is controlled by the following types of controls:

• Client Versioning Controls (Batch)

• Client Versioning Controls (CICS)

• Database Versioning Controls

• Daemon Versioning Controls

Client Versioning Controls (Batch)

This section lists the VERCL controls which can be used for Default Settings.

This section lists the VERCL controls which can be used for Versioned Link Module Entries.

This section lists the VERCL controls which can be used for Specific Jobname Entries.

Client Versioning Controls (CICS)

This section lists the VERCL controls which can be used for Default Settings.

This section lists the VERCL controls which can be used for Versioned Link Module Entries.

This section lists the VERCL controls which can be used for Specific Transaction-ID Entries.

Database Versioning Controls

This section lists the VERDB controls which can be used for Database Versioning.

Daemon Versioning Controls

This section lists the VERDM controls which can be used for Daemon Versioning.

Control Descriptions

This section provides a description of each Versioning control.

• BINDGBLS

• COFF

• DBID

• DEFAULT

• JOBNAME

• JOBTYPE

• LNKGBLXX

• OVERIDES

• SUFFIX

• SVC

• TRAN

• VRL

• WTO

BINDGBLS

COFF

DBID

DEFAULT

JOBNAME

JOBTYPE

LNKGBLXX

OVERIDES

SUFFIX

SVC

TRAN

VRL

WTO

Installation Verification

At the end of the installation process, you can perform verification checks to ensure successful installation, as follows:

• Verify Client Versioning (Batch)

• Verify Client Versioning (CICS)

• Verify Database Versioning

Verify Client Versioning (Batch)

Setting the WTO control to YES will result in job-specific details of the configuration being written to the console enabling verification, as follows:

+VER101I Jobname  Link Module Globals  SVC    DBID  
+VER101I -------- ----------- -------- ------ ------
+VER101I ADA81TST ADALNK81    BINDGBLS ASIS   ASIS  

If client versioning detects an error (for example, the required versioned link module is not available), it issues a message and rejects all Adabas commands with response 101, subcode 87.

Verify Client Versioning (CICS)

During CICS initialisation you will see a set of ADAK messages for each TRUE, each of which will say "in use by ADABAS link routine ADABAS". This is because the versioning module is invoked by each PLT routine. The versioning module ensures that the correct TRUE and link module are initialized.

Setting the WTO control to YES will result in full details of the configuration being written to the console enabling verification, as follows:

+VER101I  Criteria Link Module
+VER101I  -------- -----------
+VER101I  Default  ADABASDF   
+VER101I  DEMO     ADABASDE   
+VER101I  N426     ADABAS81   

If client versioning detects an error (for example, the required versioned link module is not available), it issues a message and rejects all Adabas commands with response 101, subcode 87.

Verify Database Versioning

If Database Versioning is active then messages will be issued to the console during nucleus initialization. These can be used to verify that the software is installed correctly, and the correct product/version sets of modules have been located. A sample of such messages follows: