The following is an overview of the steps for installing Adabas on an z/OS system.
| Step | Description | Additional Information |
|---|---|---|
|
Basic Installation Steps
|
||
| 1 | Allocate DASD space for the Adabas libraries. |
The libraries are restored from the installation tape. Refer to the section Disk Space Requirements for Libraries. |
| 2 | Allocate DASD space for the Adabas database. |
For better performance, distribute the database files over multiple devices and channels. Refer to the section Disk Space Requirements for the Database. |
| 3 | Specify the address space for running the Adabas nucleus. |
Refer to the section Adabas Nucleus Address Space Requirements. |
| 4 | Restore the Adabas libraries from the installation tape. |
Use the tape positioning information that accompanies the tape. Refer to the section Installing the Release Tape. |
| 5 | Install the Adabas SVC temporarily or permanently. |
Refer to the section Initializing the Adabas Communication Environment. |
|
Database Installation Steps
|
Steps 6-15 require changes to the setup definitions as described in section Installing an Adabas Database. | |
| 6 | Allocate and format the Adabas database with the ADAFRM utility job. | |
| 7 | Define the global database characteristics with the ADADEF utility job. | |
| 8 | Load the demonstration files with the ADALODE, ADALODV, and ADALODM jobs. | |
| 9 | Start the Adabas nucleus and test the Adabas communications with the ADANUC job. | |
| 10 | If appropriate, test Adabas address space communications by running ADAREP in MULTI mode with the CPEXLIST parameter. | |
| 11 | If appropriate, load the Adabas Online System (AOS) selectable unit into a Natural system file by running the AOSINPL job. Alternatively, install the AOS demo version. | See section Installing the AOS Demo Version. |
| 12 | Terminate the Adabas nucleus with an ADAEND operator command using the OS Modify command F. | |
| 13 | Back up the database by running the ADASAV utility job. | |
| 14 | Insert the ADARUN defaults by running the DEFAULTS job. | |
|
TP Monitor Installation
|
||
| 15 | Install the required TP link routines for Adabas. | See section Installing Adabas with TP Monitors. |
The major steps in preparing for Adabas installation are
checking for the correct prerequisite system configuration; and
allocating disk and storage space.
The minimum 3390 disk space requirements for the Adabas libraries are as follows:
| Library | 3390 Cylinders | 3390 Tracks | Directory Blocks |
|---|---|---|---|
| Load | 8 | 120 | 40 |
| Source | 3 | 45 | 20 |
| JCL | 1 | 15 | 20 |
Note:
You can isolate user programs from the Adabas load library by
creating a separate load library that contains only those modules needed to
execute user programs in multi-user mode and linked with ADAUSER. For Version
7.4, the modules required by user programs are ADAIOR, ADAIOS, ADALNK, ADAMLF,
ADAPRF, ADARUN.
The Software AG WAL library is required if you intend to use Software AG’s System Management Hub (SMH).
The following data set must be loaded and included in the STEPLIB
concatenation: WAL741.LOAD
The following data sets are required when installing the System Management Hub:
WAL741.LOAD WAL741.SRCE WAL741.JOBS WAL741.ALLAZIP WAL741.SARG
The Software AG internal product libraries (BTE - basic technologies; and APS - porting platform) are required if you intend to enable a database for universal encoding service (UES) support. These libraries are now delivered separately from the product libraries.
For UES support, the following libraries must be loaded and included in the STEPLIB concatenation:
BTE312.LDnn APS271.LDnn
—where nn is the load library level. If the library with a higher level number is not a full replacement for the lower level load library(s), the library with the higher level must precede those with lower numbers in the steplib concatenation.
Note:
If you are using an Adabas load library prior to Version 7.2.2, it
contains internal product libraries with an earlier version number and must be
ordered below the current internal product libraries in the steplib
concatenation.
Also for UES support, the following library must be loaded and included
in the session execution JCL: BTE312.ECSO
For information about setting up connections to UES-enabled databases through Entire Net-Work and ADATCP, see section Connecting UES-Enabled Databases.
The minimum disk space requirements on a 3390 disk for the internal product libraries delivered with Adabas Version 7.4 are as follows:
| Library | 3390 Cylinders | 3390 Tracks | Directory Blocks |
|---|---|---|---|
| BTE312.LD00 | 2 | 30 | 5 |
| BTE312.ECSO | 12 | 180 | 150 |
| APS271.LD00 | 5 | 75 | 55 |
The actual database space needed by Adabas depends on user requirements. The minimum 3390 disk space requirements for the database are as follows:
| Database Component | 3390 Cylinders | 3390 Tracks |
|---|---|---|
| ASSOR1 (Associator) | 20 | 300 |
| DATAR1 (Data Storage) | 60 | 900 |
| WORKR1 (Work space) | 15 | 225 |
| TEMPR1 (temporary work space) | 15 | 225 |
| SORTR1 (sort work space) | 15 | 225 |
The typical Adabas nucleus requires at least 800-1024 kilobytes to operate. The size of the nucleus address space may need to be larger, depending on the ADARUN parameter settings. Parameter settings are determined by the user.
This section explains how to:
copy data set COPY.JOB from tape to disk
modify the data set according to your local naming conventions
You can use the modified data set to copy all data sets from tape to disk. You will then need to perform the individual install procedure for each component.
Note:
If you are using SMA, please refer to the chapter Installing Software
AG Products with SMA in the System Maintenance Aid
documentation. If you are not using SMA, please follow the instructions below.
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, and <vvvvvv> is the desired volume serial number.
There are three parameters to set before you can submit 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 data sets from tape to your disk.
This section describes the installation of the Adabas router (ADASVC). The router uses cross-memory services for communication between the Adabas nucleus and the Adabas users.
The Adabas z/OS cross-memory communications service comprises two modules:
the Adabas router (ADASVC); and
the Adabas subsystem initialization routine (ADASIR).
ADASIR, executed either during IPL or by the Adabas SVC installation program (ADASIP), initializes the router’s operating environment, particularly the ID table.
ADASVC installation can be either temporary or permanent:
The Adabas SVC can be installed temporarily by executing ADASIP. The SVC is then available only until the next IPL.
Note:
Once installed, the Adabas SVC can be re-installed temporarily
using the ADASIP REPLACE option. However, no Adabas nucleus can be active
during this procedure.
Note:
It is necessary to cycle CICS after executing ADASIP to initialize
the SVC.
The Adabas SVC is installed permanently using regular operating systems procedures. The SVC then requires an IPL to become active.
Typically, the Adabas SVC is first installed temporarily using ADASIP. This makes Adabas available immediately without the need to wait for an IPL. Meanwhile, preparations are usually made for permanent installation at the next IPL.
Regardless of the installation procedure selected, an available SVC table entry must be allocated to the Adabas router (ADASVC). SVC table entries are defined in the member IEASVCxx of SYS1.PARMLIB.
The SVC table entry in the operating system for an ADASVC must contain the following information:
| Offset | Label | Description |
|---|---|---|
| 0 | SVCEP | SVC entry point address. |
| 4 | SVCATTR1 |
Must indicate type 2 SVC (flag bit SVCTP2 set—X’80’) or type 3 or 4 SVC (flag bits SVCTP34 set—X’C0’): ADASIR changes a type 1, 5, or 6 SVC to type 2. May indicate that APF-authorization is needed for this SVC (flag bit SVCAPF set—X’08’): if set, all targets and users must be APF-authorized. |
| 6 | SVCLOCKS | Must contain all zeros. ADASIR sets SVCLOCKS to zeros. |
The subsystem name contained in the four-character field SUBSYS at ADASVC offset X’28’ (the default is “ADAB”) must be the same as that specified in the IEFSSNxx member of SYS1.PARMLIB. If the name is not the same, ADASIR ends with an ADAS12 message and condition code 2, and Adabas is not usable.
If the Adabas SVC is to reside in the fixed LPA, add an entry to an IEAFIXxx member of SYS1.PARMLIB.
The Adabas SVC should be initialized with ADASIP/ADASIR in order to guarantee full functioning of all Adabas nuclei.
Once you have restored the Adabas installation tape, use a local editor to customize the job JCLLINK (used to link ADASIR, ADASIP, and ADASVC) as follows:
to perform temporary router installation:
Link ADASIP into an APF-authorized library as an authorized module.
Link ADASIR and ADASVC into APF-authorized libraries:
Place ADASVC in an APF-authorized library in order to run ADASIP.
Place ADASIR in an APF-authorized library concatenated to SYS1.LINKLIB defined in source member LNKLSTxx located in SYS1.PARMLIB.
Execute ADASIP to install the SVC.
Customize and run the job ADASIP to dynamically add the Adabas SVC without an IPL.
to perform permanent router installation:
Link the Adabas SVC (ADASVC) which has been renamed according to the SVC routine renaming rules (for example, type 3 SVCs must have names of IGC00nnn, where nnn is a signed decimal SVC number) into SYS1.LPALIB as a permanent step for ADASIR.
Link ADASIR into SYS1.LINKLIB or into an APF-authorized library concatenated to SYS1.LINKLIB with the LNKLSTxx member of SYS1.PARMLIB.
Note:
ADASIR is not reentrant, and therefore should not be linked into
SYS1.LPALIB.
Customize and run the job JCLUPDT to add a new entry with the correct format.
IPL z/OS with the CLPA option to install and initialize the Adabas communication environment.
ADASIP performs the following functions:
acquires memory in the specified CSA subpool for the Adabas SVC and a subsystem communication vector table (SSCT)
loads the Adabas SVC into the acquired CSA space
modifies the SVC table entry as required by the Adabas SVC
optionally deletes an SSCT for the same subsystem name from the SSCT chain
adds the new SSCT to the SSCT chain
invokes the ADASIR program
If any error is detected, ADASIP backs out all completed activities and terminates operation with a user abend specifying the error.
The following JCL links ADASIP, located in ADABAS.Vvrs.LOAD, into an APF-authorized library as an authorized module:
//LNKSIP EXEC PGM=IEWL //SYSPRINT DD SYSOUT=* //SYSUT1 DD SPACE=(CYL,(1,1)),UNIT=SYSDA //ADALIB DD DSN=ADABAS.Vvrs.LOAD,DISP=SHR //SYSLMOD DD DSN=apflibname,DISP=SHR //SYSLIN DD * INCLUDE ADALIB(ADASIP) SETCODE AC(1) NAME ADASIP(R)
ADASIP parameters have the following syntax:
CONSNAME=c,IDTSPL=i,LEAVE=l,NRIDTES=n,REPLACE=r,SUBSYS=su, SVCNR=svcn,SVCSPL=svcs
—where
| c | is the console name to which operator messages are written. If omitted, messages are issued using ROUTCDE=2, master Console Information. |
| i | is the ID table subpool: see the ADASIR IDTSPL parameter for details. |
| l | indicates whether ADASIR should display message ADAS11 or ADAS12 on the operator console: see the ADASIR LEAVE parameter for details. |
| n | is the number of ID table entries: see the ADASIR NRIDTES parameter for details. |
| r | indicates whether or not an existing SSCT for the same subsystem name is to be replaced. Y for yes or N for no (N is the default). Use this option to replace any type of Adabas SVC (for example, when installing a new SVC version). |
| su | is the subsystem name. This parameter is required. Each instance of the Adabas SVC must have a unique subsystem name. |
| svcn | is the Adabas SVC number: see the ADASIR SVCNR parameter for details. |
| svcs | is the Adabas SVC and SSCT subpool: 228 for fixed CSA or 241 for pageable CSA (default: 241). |
The following are valid ADASIP parameter abbreviations:
| Parameter | Abbreviation |
|---|---|
| CONSNAME= | C= |
| IDTSPL= | I= |
| LEAVE= | L= |
| NRIDTES= | N= |
| REPLACE= | R= |
| SUBSYS= | SU= |
| SVCNR= | SVCN= |
| SVCSPL= | SVCS= |
All parameters are optional except SUBSYS and SVCNR. If specified, the parameters IDTSPL,LEAVE, NRIDTES, SUBSYS, and SVCNR are passed to ADASIR without being verified.
JCL similar to the following should be used to execute ADASIP:
// EXEC PGM=ADASIP,PARM=parameters //STEPLIB DD ... //SVCLIB DD ... //SIRLIB DD ...
The data set defined by the STEPLIB DD statement must be an APF-authorized library containing the APF-authorized program ADASIP. Since ADASIP is neither reentrant nor refreshable, the data set cannot be SYS1.LPALIB.
The data set defined by the SVCLIB DD statement must be an APF-authorized library containing the Adabas SVC with either the name or alias ADASVC.
The data set defined by the SIRLIB DD statement must contain the ADASIR program. Since ADASIR is neither reentrant nor refreshable, the data set may not be SYS1.LPALIB.
ADASIP terminates with a U0481 abend if the parameter input is incorrectly specified.
The IBM job control convention for continuing the PARM parameter is:
// EXEC PGM=ADASIP,PARM=(’parameters ....’, X // ’parameters’)
—where X in column 72 is a continuation character. The following restrictions also apply to JCL statements:
a comma is required after the end-quote on a line that is to be continued
a non-blank continuation character is required in column 72 of each line that is to be continued, and the continuation line must start within columns 4-16
a comma is not permitted between the last parameter and the end-quote on the line to be continued because JCL automatically inserts a comma between parameters when concatenating continuation strings:
// ...PARM=(’CONSID=3’, X // ’SUBSYS=ADAB’, X // ’SVCNR=249’)
—results in an equivalent line of
CONSID=3,SUBSYS=ADAB,SVCNR=249
The ADASIR program is invoked
by the ADASIP program to install the Adabas SVC temporarily, or
by z/OS to install the Adabas SVC permanently.
ADASIR receives control during either master scheduler initialization or ADASIP execution. The operator is prompted for any value that has been incorrectly zapped or assembled (refer to the Adabas Messages and Codes for specific message descriptions). If an error is found during the processing of parameters specified in the IEFSSNxx member or passed by ADASIP, the operator is prompted for all of the values.
If the SVC table entry is incorrect, ADASIR prompts the operator for permission to change the entry (if SVCTAB=P, the default, is specified). If any errors are detected, they must be corrected and either another IPL must be done or ADASIP must be rerun before the Adabas SVC can be used.
The ADASIR module must be linked into an APF-authorized library.
The following JCL links ADASIR, located in ADABAS.Vvrs.LOAD, into SYS1.LINKLIB:
//LNKSIR EXEC PGM=IEWL //SYSPRINT DD SYSOUT=* //SYSUT1 DD SPACE=(CYL,(1,1)),UNIT=3350 //ADALIB DD DSN=ADABAS.Vvrs.LOAD,DISP=SHR //SYSLMOD DD DSN=SYS1.LINKLIB,DISP=SHR //SYSLIN DD * INCLUDE ADALIB(ADASIR) NAME ADASIR(R)
ADASIR parameters have the following syntax:
IDTSPL=i,LEAVE=l,NRIDTES=n,SVCNR=svcn,SVCTAB=svct
| Variable | Description |
|---|---|
| i | The ID table subpool: 228 for fixed CSA or 241 (the default) for pageable CSA. |
| l | Indicates whether message ADAS11 or ADAS12 is to be displayed on the operator console: Y for yes or N (the default) for no. |
| n | The ID table entry count, which can range from 1 to a maximum specified at offset X’146’ in the CSECT IEAVESVT of the z/OS nucleus (see section Requirements for Cross-Memory Services). |
| svcn | The Adabas SVC number (200-255). |
| svct | Indicates whether or not the operator should be prompted for permission to update the SVC table entry. Enter P (the default) to receive a prompt, or N for no prompt. P is recommended if a possibility exists that the SVC table entry will not be what ADASIR expects. |
The following are valid abbreviations for ADASIR parameters:
| Parameter | Abbreviation |
|---|---|
| IDTSPL= | I= |
| LEAVE= | L= |
| NRIDTES= | N= |
| SVCNR= | SVCN= |
| SVCSPL= | SVCS= |
Note:
The ADASIR module must be linked into an APF-authorized
library.
To prepare for permanent SVC installation, an entry must be made in either a new or existing member having the name IEFSSNxx in SYS1.PARMLIB. This entry is an 80-character record with the following format:
SUBSYS SUBNAME(cccc) CONSNAME(consname) INITRTN(ADASIR) INITPARM(’parameters’) comments
—where
| cccc | is the 1- to 4-character subsystem name. This name and the name specified in the Adabas SVC at offset X’28’ must be the same. The name provided in the SVC is ADAB; any other name must first be zapped into the SVC before being specified for cccc. |
| consname | The name of the console to which ADASIR will direct any messages. If omitted messages will be issued with ROUTCDE=2, Master Console Information. |
| ’parameters’ | ADASIR parameters. If there is more than one parameter, values must be enclosed in single quotation marks and a comma placed between the parameters. |
| comments | Comments are optional and must be preceded by at least one space. |
If the subsystem name does not match, ADASIR abends with an ADAS12
message and condition code 2; the Adabas OS/390 or z/OS communication
environment is not initialized. Re-IPL OS/390 or z/OS, specifying
SSN=xx if necessary. If this
is the first IPL with a type 3 or 4 Adabas SVC, specify CLPA as one of the
SET parameters.
If an error is encountered while processing any of the parameters obtained from the IEFSSNxx member or passed from ADASIP (message ADAS05), the operator is prompted to reenter all of the parameters. If the SVC table entry is not correct (message ADAS09) then, depending on the value of the SVCTAB parameter, either the operator is prompted (message ADAS10) for permission to change the SVCTAB parameter, or it is simply changed (message ADAS15).
A Version 6.2 ADASIP/ADASIR can be used to install a Version 7 Adabas SVC (and the reverse). However, Software AG recommends that you use the same release of ADASIP/ADASIR to install the SVC/router as the SVC/router itself.
The ADASIR messages and their meanings are described in the Adabas Messages and Codes.
Link the Adabas SVC with the name or alias ADASVC into an APF-authorized library. ADASVC must be linked with AMODE=31 and RMODE=24, the default.
The following example shows how to link the SVC:
// (job card) //LKED EXEC PGM=IEWL, // PARM=’XREF,LIST,NCAL,LET,MAP,RENT,REFR,REUS’ //SYSPRINT DD SYSOUT=X //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSLMOD DD DSN=SYS1.LINKLIB,DISP=SHR <--Target loadlib //ADALIB DD DSN=user.loadlib,DISP=SHR <--ADASVC loadlib //SYSLIN DD * MODE AMODE(31),RMODE(24) INCLUDE ADALIB(ADASVC) NAME ADASVC(R) /*
Note:
If the SVC is linked with a name other than ADASVC when preparing to
upgrade to a permanent installation, the SVC must have an alias of ADASVC. When
dynamically loading the Adabas SVC, ADASIP searches for the module ADASVC in
the library specified by the SVCLIB DD statement.
Software AG recommends using a type 3 or 4 SVC for the Adabas SVC.
SVC types 1 and 6 are not supported.
If the Adabas SVC is to be type 2, link it into SYS1.NUCLEUS as the system nucleus IEANUC0x.
This nucleus must contain an SVC table entry for an enabled type 2 SVC, which must be defined during SYSGEN.
Then include linkage editor control statements similar to the following with those needed to link a nucleus:
CHANGE ADASVC(IGCnnn) ---> nnn is the SVC number in decimal INCLUDE ADALIB(ADASVC) ---> ADALIB contains the Adabas SVC
To install the Adabas SVC as type 3 or 4, link the Adabas SVC with the appropriate name into SYS1.LPALIB. ADASVC must be linked with AMODE=31 and RMODE=24 (the default).
The following example shows how to relink the SVC:
// (job card) //LKED EXEC PGM=IEWL, // PARM=’XREF,LIST,NCAL,LET,MAP,RENT,REFR,REUS’ //SYSPRINT DD SYSOUT=X //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSLMOD DD DSN=SYS1.LPALIB,DISP=SHR <--Target Loadlib //ADALIB DD DSN=ADABAS.Vvrs.LOAD,DISP=SHR <--ADASVC loadlib //SYSLIN DD * MODE AMODE(31),RMODE(24) CHANGE ADASVC(IGC00nnp) <- where nn are the first two digits of the SVC in decimal and INCLUDE ADALIB(ADASVC) p is the character corresponding to the x’Cn’ NAME IGC00nnp(R) ----> (n is the last digit of the SVC number in decimal) * /*
Once you have restored the Adabas installation tape and have installed the ADASVC, you can
migrate an existing Adabas database to the new version; or
install a new version of the Adabas database.
Messages or codes that occur during the installation are described in the Adabas Messages and Codes; utilities are described in the Adabas Utilities.
Use the ADACNV utility to migrate existing databases to new releases of Adabas (SMA job number I051). See Adabas Utilities for more information.
Customize and run the ADAFRM utility job to allocate and format the Adabas database. The following must be customized:
data set names for the database and libraries;
volumes for libraries and data sets for the database;
space allocation for data sets for the database;
the Adabas SVC number, the database ID, and database device type(s);
sizes of the data sets for each ADAFRM statement.
Customize and run the ADADEF utility job to define the global definition of the database. The following must be customized:
data set names of the database and libraries;
the Adabas SVC number, the database ID, and database device type(s);
ADADEF parameters.
Customize and run the job:
ADALODE to load the sample demo file EMPL;
ADALODV to load the sample demo file VEHI; and
ADALODM to load the sample demo file MISC.
For each job, the following items must be customized:
data set names for the database and libraries;
the Adabas SVC number, the database ID, and database device type(s);
ADALOD parameters.
Customize and run the job ADANUC to start the Adabas nucleus. The following must be customized:
data set names for the database and libraries;
the Adabas SVC number, the database ID, and database device type(s);
ADANUC parameters.
Customize and run the job ADAREP in MULTI mode with the CPEXLIST parameter to test Adabas address space communications. The following must be customized:
data set names for the database and libraries;
the Adabas SVC number, the database ID, and database device type(s);
ADAREP parameters.
Customize and run the job AOSINPL to load the Adabas Online System (AOS) into a Natural system file using a batch version of Natural 3.1 or above. The following items must be customized:
data set names of the database and libraries;
the Adabas SVC number, the database ID, and device type(s);
the Natural INPL parameters and system file number.
Alternatively, install the AOS demo version delivered with Adabas: see the section Installing the AOS Demo Version.
Communicate with the Adabas nucleus to terminate the session either with an ADAEND operator command using the OS Modify command
F jobname,ADAEND
—or
P jobname
—where jobname is the job or task name of the started nucleus.
Customize and run the ADASAV utility job to back up the database. The following must be customized:
data set names of the database and libraries;
the Adabas SVC number, the database ID, and device type(s);
ADASAV parameters.
The member DEFAULTS in the Adabas JCL library can be modified to set the ADARUN defaults. The following must be customized:
data set names of the database and libraries;
ADARUN user defaults:
device type(s) (default: 3380)
SVC number (default: 249)
database ID (default: 1)
Customize and run the DEFAULTS job to set the ADARUN defaults using the OS ZAP utility.
Refer to the section Installing Adabas with TP Monitors for a description of the TP link routine procedure.
In the past, the presence of multiple SVCs with the same subsystem ID has resulted in a single ID table being used by different SVCs. This has caused problems, some of them serious (abnormal nucleus termination or corruption of the database).
To eliminate this danger, the Version 7 SVC checks to ensure that the SVC accessing the ID table is the same as the one that was used by ADASIP/ADASIR to initialize the table. If the SVCs are not the same, an abend 650 occurs.
Abend 650 occurs when an incorrect SVC number is specified in the ADARUN parameters for a nucleus. It can occur during Adabas initialization, during the first Adabas call from a user program, or when the ID table is queried by another Software AG server such as Entire Net-Work.
Due to the implementation of cross-memory services in OS/390 and z/OS, the following points should be noted when running an Adabas nucleus in MULTI mode:
a maximum of one step of a job can establish the cross-memory environment. This means that a job can include at most one step that is a target (for example, an Adabas nucleus).
cross-memory accesses may not be made to a swapped-out address space. Therefore, the address space of an Adabas nucleus is set to “nonswappable” for the duration of the nucleus session. This can increase the installation’s real storage requirements. This behavior is documented in the IBM manual Extended Addressability Guide, chapter Synchronous Cross-Memory Communication.
when a nucleus with an active cross-memory environment terminates either normally or abnormally, the entire address space including any initiator is also terminated.
The ASID representing this address space is not reassigned until the next IPL. Therefore, you should choose a sufficiently high value for the MAXUSERS parameter in the active IEASYSxx member of SYS1.PARMLIB or—if your system supports it—the RSVNONR parameter in the same member can be adjusted accordingly. Also, the Adabas nucleus should not be stopped and started without good reason.
This is described in the manuals referred to in the topics Recovery Considerations and Resource Management. Additional information can be found in IBM APARs OZ61154, OZ61741, and OZ67637.
To make its services available to all address spaces in the system, the Adabas nucleus must obtain a system linkage index (LX) from OS/390 or z/OS. The LX is a reserved slot in the linkage space of all address spaces, and permits system-wide linkage to all address spaces.
The number of LXs set aside by OS/390 or z/OS for system use is rather small (usually 165 out of a possible 2048).
Because of the way OS/390 and z/OS use cross-memory services, system LXs obtained by Adabas cannot be returned to OS/390 or z/OS until the next IPL. However, the system that owns the LXs can reuse them, even for a different address space. Adabas makes use of this feature by saving used LXs in the ID table, where they are available to future nuclei.
The number of system LXs can be specified in the member IEASYSxx contained in SYS1.PARMLIB, using the NSYSLX parameter. If you change this value, you must perform an IPL to make the change effective.
To determine an appropriate NSYSLX value, consider the following points:
some LXs are probably already being used by other system functions. Therefore, the chances of creating an LX shortage for other users is small.
Adabas requires one system LX for each Adabas nucleus (or any other target) that will be active concurrently. A value of decimal 64 would allow concurrent execution of up to 64 Adabas nuclei or other targets with little chance of restricting other components using LXs.
Entire Net-Work Version 5 uses only one LX and one ID table entry, regardless of how many remote databases it must represent. This is unlike the pseudo-MPM concept of earlier Entire Net-Work versions.
whenever ADASIP is executed with the REPLACE option, all LXs saved in the current ID table are lost until the next IPL.
Likewise, if a session ends either normally with the FORCE operator command or abnormally during ESTAE processing (for example, by an S222 operator cancel or by a S722 spool limit exceeded abend during a snap dump), the LX also cannot be recovered until the next IPL.
Any commands sent to these targets receive an S0D6 abend. Any attempt to restart the nucleus results in an ADAM98 message DUP ID (LOCAL), followed by an abend. To resolve both of these problems, restart the nucleus with the ADARUN FORCE=YES and IGNDIB=YES parameters.
The first target that tries to obtain a system LX when none is available ends with an S053 abend code and reason code 0112. No additional targets can be started until the next IPL.
The only CSA space used by Adabas Version 7 router is the following:
96+32*NRIDTES (where NRIDTES is the ADASIR or ADASIP parameter described above) every time either program is successfully executed.
LEN(ADASVC)+SSCTSIZE (equal to 36 bytes) each time ADASIP executes successfully.
Adabas uses Global Resource Serialization (GRS) to synchronize the execution of Adabas nuclei and utilities at certain points in their processing. It is vital that GRS be set up correctly in the system so that GRS requests by Adabas will be effective.
When setting up GRS, consider the following:
Adabas uses the GRS macros ENQ and DEQ with systems-wide scope (SCOPE=SYSTEMS) and major name ‘ADABAS’ (QNAME).
if the database resides on disks that are shared between multiple images of the operating system (multiple LPARs or machines) and Adabas nuclei or utilities may be run against the database from several of these images, make sure that GRS is installed in a way that systems-wide ENQ requests are effective on all of these system images.
CPU usage is reduced considerably by using EXCPVR.
To use EXCPVR, you must
APF-authorize ADARUN; and
locate all Adabas modules in APF-authorized libraries.
When placed in an APF-authorized library, ADARUN allows the Adabas nucleus and utilities to use EXCPVR. All Adabas modules except the Adalink must run with RMODE=24 (the default); the Adalink can run with any RMODE.
When the EXEC statement specifies PGM=ADARUN, AMODE is determined as follows:
The default AMODE=31 is used unless ADARUN was relinked using either the AMODE=24 EXEC statement parameter or the MODE AMODE(24) linkage editor control statement.
An AMODE of 31 is changed to 24 before affected macros (data management, for example) are run, and then changed back to 31 thereafter.
Adabas performance can be improved by using EXCPVR to improve channel program translation time. For Adabas to invoke EXCPVR automatically, the Adabas modules must be in an APF-authorized library and ADARUN must be linked with SETCODE AC(1), the default, as shown in the following example:
//LINKRUN EXEC PGM=IEWL,PARM=’REUS’ //SYSPRINT DD SYSOUT=* //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //ADALIB DD DSN=user.loadlib,DISP=SHR //SYSLMOD DD DSN=user.loadlib,DISP=SHR <==APF−AUTHORIZED LIBRARY //SYSLIN DD * INCLUDE ADALIB(ADARUN) SETCODE AC(1) NAME ADARUN(R)
The ADARUN module delivered in the Adabas load library is not reusable. If you need a shareable ADARUN, you will need to relink it with the REUS=YES link-edit attribute.
Linking ADARUN with the reusable option permits several programs running in the same address space to share the same ADARUN and ultimately, the same copy of ADALNK. This is important when it is necessary to have only one Adabas user ID for the different programs, and is also needed if single copies of ADALNK user exits are required.
To create a shareable ADARUN, use the sample job JCLLINRR in the MVSJOBS library to relink it with the REUS attribute.
If both nonreusable and reusable versions of ADARUN are required, they must be located in different load libraries since both must be loadable using the name ADARUN.
Adabas can acquire a number of its required areas, including buffer space, above the 16-MB addressing limit, allowing Adabas to increase the buffer pool size.
To reverse the space allocation to be below the 16-MB limit, set the AMODE value in the MODE statement in the example below to AMODE(24):
//LINKRUN EXEC PGM=IEWL,PARM=’REUS’ //SYSPRINT DD SYSOUT=* //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //ADALIB DD DSN=user.loadlib,DISP=SHR //SYSLMOD DD DSN=user.loadlib,DISP=SHR <=APF-authorized library //SYSLIN DD * MODE AMODE(24),RMODE(24) SETCODE AC(1) INCLUDE ADALIB(ADARUN) NAME ADARUN(R)
In addition, Adabas must be run with a sufficient REGION specification, either on the JOB or EXEC statement or as an installation default. For example:
//BIG JOB ...,REGION=30M,...
Adabas can exploit storage occupying real pages above the 2-gigabyte line. This capability allows Adabas I/Os to use 64-bit real addresses.
Support for 64-bit real storage is available whether you are running APF-authorized (using EXCPVR) or not (using EXCP). The run mode is indicated in the ADAI65 message:
ADAI65 EXCPVR IS {BEING | NOT BEING} USED FOR THIS RUN IN ESA64 MODE
Support for 64-bit real storage requires either
OS/390 R10 in ARCHLEVEL=2 (that is, z/architecture mode); or
z/OS 1.2 or above
on a processor of the IBM 2064 family with an LPAR greater than 2 gigabytes for real storage allocation.
IBM supports 64-bit virtual storage only for z/OS 1.2 or above.
Software AG provides support for IBM’s 64-bit virtual storage with the product Adabas Caching Facility (ACF). Contact your Software AG representative for more information.
A demo of Adabas Caching Facility is delivered in the ADA741.ALLINPL file.
Use the OS/390 or z/OS AMASPZAP utility to apply zaps in the respective operating system; this method verifies (VER) and replaces (REP) data. The following sample JCL executes AMASPZAP:
//ADAZAP JOB //STEP1 EXEC PGM=AMASPZAP //SYSPRINT DD SYSOUT=X //SYSLIB DD DSN=ADABAS.Vvrs.LOAD,DISP=SHR //SYSIN DD * (zap control statements) /* //
—where the following are examples of zap control statements:
NAME membername csectname VER displacement data REP displacement data IDRDATA (up to eight bytes of user data) * (comment)
Note:
In VER and REP statements, spaces must be used to separate command,
displacement, and data. Commas are acceptable data separators; however, commas
with spaces or spaces alone are not, and may cause errors.
Note:
For information about connecting a database that is enabled for data
conversion using the universal encoding service (UES), see the section
Connecting UES-Enabled
Databases.
One or two user exits may be linked with an Adalink routine (SMA job number I088):
UEXITB receives control before a command is passed to a target with the router 04 call.
Note:
Special commands emanating from utilities and from Adabas Online
System are marked as physical calls. These calls must be bypassed in user
exits. These calls have X‘04’ in the first byte (TYPE field) of the command’s
Adabas control block (ACB). UEXITB must check this byte and return if it is set
to X‘04’. Be sure to reset R15 to zero on return.
UEXITA receives control after a command has been completely processed by a target, the router, or by the Adalink itself.
At entry to the exit(s), the registers contain the following:
| Register | Contents |
|---|---|
| 1 | Address of the UB.
If the flag bit UBFINUB is reset, the contents of the halfword at Adabas + X’86’ have been moved to UBLUINFO. If those contents are greater than zero, the two bytes starting at UBINFO (UB+X’40’) have been set to zero. If UBFINUB is set, no changes can be made to the UB or ACB (except for ACBRSP). |
| 2 | Address of a 16-word save area (for ADALNC only) |
| 13 | Address of an 18-word save area (for non-CICS Adalink exits) |
| 14 | Return address |
| 15 | Entry point address: UEXITB or UEXITA |
Any registers except register 15 that are modified by the user exits must be saved and restored; the address of a save area for this purpose is in register 13 (or register 2 for ADALNC).
If at return from UEXITB register 15 contains a value other than zero, the command is not sent to the target but is returned to the caller. The user exit should have set ACBRSP to a non-zero value to indicate to the calling program that it has suppressed the command: response code 216 is reserved for this purpose.
The UEXITB exit may set the UB field UBLUINFO to any lesser value, including zero; an abend occurs if the user exit sets UBLUINFO to a greater value. The UBLUINFO length cannot be changed when any other exit is used; for example, Adabas Review or Adabas Fastpath.
The user information received by a UEXITA exit may have been modified; this modification may include decreasing its length, possibly to zero, by any of the Adalink user exits.
An Adalink routine can return the following non-zero response codes in ACBRSP:
| Response Code | Description |
|---|---|
| 213 | No ID table |
| 216 | UEXITB suppressed the command |
| 218 | No UB available |
At least the following three equates, described at the beginning of the source, can be modified before an Adalink routine is assembled. In some Adalink routines, however, the corresponding information can be zapped:
| Equate | Description |
|---|---|
| LOGID | The default logical ID, ranging in value from 1 to 65535. The default is 1. |
| LNUINFO | The length of the user information to be passed to Adalink user exits, ranging in value from 0 to 32767. The default is 0. |
| SVCNR | The Adabas SVC number; its range of values and
the default depend on the operating system. This value can be provided as
SYSPARM value for assembly of the following Adalink routine:
//EXEC PGM=ass,PARM=‘......,SYSPARM(svcnr)’ |
The first 152 (X’98’) bytes of all Adabas Adalinks must maintain the following structure:
| Offset | Label | Contents | Meaning |
|---|---|---|---|
| 00 | ADABAS | Entry code | |
| 12 | CL6’ADALNx’ | Program name | |
| 18 | XL4’yyyymmdd’ | Assembly date | |
| 1C | A(ZAPTAB) | Address of zap table | |
| 20 | PATCH | XL96’00’ | Patch area |
| 80 | LNKLOGID | AL2(LOGID) | Default logical ID (default: 1) |
| 82 | 82 XL2’00’ | Reserved | |
| 84 | LNKSVC | SVC SVCNR | Executable SVC instruction for Adabas SVC (default: operating-system-dependent) |
| 86 | LUINFO | Y(LNUINFO) | Length of user information (default: 0) |
| 88 | VUEXITA | V(UEXITA) | Address of user exit after call (weak) |
| 8C | VUEXITB | V(UEXITB) | Address of user exit before call (weak) |
| 90 | ADABAS51 | CL8’ADABAS51’ | IDT ID |
ADAUSER is a program that links the user to Adabas. It is specific to an operating system and is independent of release level and mode. It can be used in batch and in some TP environments (such as TSO).
ADAUSER operates in the following way:
ADAUSER contains the entry point ADABAS and should be linked with all user programs that call Adabas. No other programs containing the CSECT or entry point name ADABAS can be linked in these load modules/phases.
on the first call to Adabas, ADAUSER loads the latest version of ADARUN. This makes the calling process release-independent. Subsequent Adabas calls bypass ADARUN.
ADARUN processes its control statements. If the ADARUN PROGRAM parameter has the (default) value USER, ADARUN loads ADAIOR and, depending on whether the ADARUN MODE parameter specifies MULTI or SINGLE, loads the appropriate TP Adalink or ADANUC, respectively. This makes the calling process mode-independent.