Version 7.4.4

Installing Adabas With TP Monitors

This section provides information needed to install Adabas with teleprocessing (TP) monitors TIAM and UTM.


The Adabas API for BS2000

The Adabas Version 7 application programming interface (API) comprises the modules:

ADALNK contains the combined functionality of all the ADALNx modules of previous Adabas versions. Software AG recommends that you link ADAUSER to the application program and use the entry point ADABAS on the API call.

For compatibility with existing applications, ADALNK contains the following entry points:

Entry Point TP Monitor
ADALNK Batch / TIAM
ADALNR Batch / TIAM (reentrant)
ADALNN UTM running Natural
ADALNU UTM with Assembler or a 3GL language

ADALNK and ADAL2P are reentrant. ADAUSER, which is supplied as source to allow modification, can be made reentrant if the user application provides a 4-byte anchor area.

Because ADALNK is reentrant, parameter items previously moved into ADALNK are now found in SSFB2C.

The symbol “ADABAS” is no longer in ADALNK, but in ADAUSER.

The symbol “ADALNR” is offset X’C’ (decimal 12) bytes into the start of ADALNK. If fields are to be accessed in this version of ADALNK, their offsets have changed accordingly.

ESD Symbols Used in the Adabas API

The following symbols have a special meaning in the Adabas API:

Symbol Meaning
ADAUSRID identification area used by Natural; identifies the caller as Natural
AUTUSRID identification area used by ADAUTM
CMSTART identifies the batch Natural driver
KDCKB area in UTM holding the user/task ID
KDCUTMD identifier that the carrier is UTM
KDCUTMID alternative identifier that the carrier is UTM

Software AG advises you not to define or write-access any of these symbols in applications that also use the Adabas API.

ADAUSER

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.

Software AG recommends that you link ADAUSER to your applications because it:

ADAUSER propagates symbols to the loaded API interface, which can be used to pass user data or determine the carrier system the application is using. ADALNK does not do this. If ADALNK is to be linked, the whole API must be linked to the application.

ADAUSER Loading ADALNK

The following file statement assigns a SAM/V dataset for the ADALINK parameters:

/SET-FILE-LINK DDLNKPAR,samv-dataset

If the file link DDCARD is specified and the application is not running on UTM, ADAUSER loads ADARUN. This is the traditional API.

If the file link DDCARD is not present, ADAUSER loads ADALNK. In this case, the routing information (idt_name,dbid) and the Adabas Review buffer size can be defined in the file link DDLNKPAR.

ADAUSER Loading ADARUN

If the file link DDLNKPAR is not specified, ADAUSER loads ADARUN for using prefetch and multifetch. The routing and Adabas Review buffer parameters are then to be delivered in the file link DDCARD or *SYSDTA.

The following file statement assigns the proper Adabas module library modlib:

/SET-FILE-LINK DDLIB,modlib

ADAUSER can load modules from several libraries. If the ADARUN-defined library is found in the catalog, it becomes the primary library.

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:

This makes ADAUSER mode-independent.

ADAUSER2

ADAUSER2 is a program that allows Natural to load a COBOL module where Natural and COBOL have separate Adabas session IDs. ADAUSER2 is delivered in the ADAvrs.SRC library and must be assembled before it can be used.

Fixed Linking of ADALNK or ADAUSER

To resolve external symbols in the application module, link the following modules to it:

If you are linking ADALNK, ADAL2P, and SSFB2C to the application module and you need to resolve the ADABAS symbol as well, you can alternatively do one of the following:

Then re-assemble the ADALNK using the macros supplied in the ADAvrs.MAC library and link it to the application.

Routing and Adabas Review Parameters

Routing parameters are used to locate the application’s target database:

DBID=
IDTNAME=

If the application requires an Adabas Review buffer, the following parameter is used:

LRVINFO=256

If ADALNK has been linked or loaded, these parameters are found under the link name DDLNKPAR. ADAL2P reads the data from DDLNKPAR and holds it in SSFB2C.

If ADAUSER has been linked or loaded and

ADARUN must be loaded in order to load and install the Adabas prefetch components:

ADARUN PROG=USER,PREFETCH=YES

Presetting Parameters in SSF2BC

Routing, Adabas Review, and some configuration information can be preset in SSFB2C using the delivered source module in ADAvrs.SRC and the macro B2CONFIG from ADAvrs.MAC:

SSFB2C Parameter Description
IDTNAME=ADAxxxxx ID table where the database runs
LRVINFO=256 set up Adabas Review buffer
X48=N turn off the Natural version 2.3 IPC X‘48’ call logic

For example, the following presets routing to database 99 on the IDTNAME ADA00009:

SSFB2C CSECT
B2CONFIG DBID=99,IDTNAME=ADA00009
END

ADALNK

When loaded, ADALNK attempts to read and process control statements from its parameter dataset. Entries in the parameter dataset appear in the following format:

ADALNK IDTNAME=ADA12345
ADALNK DBID=17

The ADALNK control statements are delivered with the default values specified in the following discussion. Changing default settings by using zaps or by re-assembling ADARUN and ADALNK should be the rare exception.

Note:
In a future version of Adabas, it will not be possible to change ADARUN and ADALNK parameters with zaps.

ADALNK Parameters

Note:
Do not specify ADALNK statements in ADARUN nuclei, Entire Net-Work, ADAUSER, or utility contexts. If you do, a warning message (ADAK06) is reported, the ADALNK statements are ignored, and processing continues.

Parameter Syntax Description
DBID= {nnnnn | 1 }
Sets the default database ID. The minimum value is 1; maximum value is 65535. The default is 1.
DISACLOS={ YES | NO }
Determines whether or not Adalink is to close all communication after executing the CL command to the last connected database so that the user task can issue BS2000 WRCPT macros (not available for ADALNN, ADALNR, or ADALNU Adalinks). The default is NO.
GROUPS={ YES | NO }
Determines whether or not the communication items are valid for all logon user IDs with no restriction (NO, the default) or whether they are valid only for the logon user ID of the present task (YES). See also the ADARUN GROUPS parameter in Adabas Operations.
IDTNAME={ ADABAS5B | ADAccccc }
Specifies the name of the ID table to be accessed. This name must be the same as the nucleus’ ADARUN IDTNAME parameter, if specified, which must be 8 characters beginning with ADA. The default is ADABAS5B.
LRVINFO={256 | 0 }
Determines whether the Adabas Review user exit B is inactive (0, the default) or active (256). Values other than 0 and 256 are not allowed.
X48={ YES | NO }
Determines whether or not X48 call processing is available to an application so that it can build its own 28-byte communication ID to identify internal Adabas resources used by a logical transaction.

ADALNK Parameter Service

The ADALNK parameter service coordinates ADARUN, ADALNK, and SSF parameters. It comprises three modules:

The parameters in the delivered SSF2BC module contain the same defaults as associated ADARUN and ADALNK parameters and can be modified with the help of the ADARUN or ADALNK parameters. In some cases, it is desirable to hide these parameters.

Linking ADALNK

The ADALNK parameter service considers the SSFB2C configuration module:

If the INCLUDE statement for ADAL2P is omitted, an unresolved VCONS occurs and the parameter service will not be available.

B2CONFIG Macro

If other defaults are required, the SSF configuration module can be re-assembled. The macro B2CONFIG is delivered for this purpose.

The following operands are available:

Operand Syntax Description
ALNKPRT={ NO | YES }
Permits or inhibits the creation of the ADALNK parameter services’ protocol dataset.
DBID= {nnnnn | 1 }
Sets the default for the ADARUN and ADALNK parameter DBID=n. The maximum value is 65535; the default is 1.
DISACLOS={ YES | NO }
Sets the default of the ADALNK parameter DISACLOS.
ENVNAME=cccccccc
Sets the default for the ADARUN and ADALNK parameter IDTNAME. The operand must contain exactly 8 alphanumeric characters.
ENVSCOPE= {GROUP | GLOBAL }
Sets the default for the ADARUN and ADALNK parameter GROUPS. Specify:
  • ENVSCOPE=GROUP for ADALNK GROUPS=YES

  • ENVSCOPE=GLOBAL for ADALNK GROUPS=NO

LRVINFO={256 | 0 }
Sets the default for the Adalink parameter LRVINFO.
NUMGES={ nnn | 6000 }
Determines the maximum number of global event control blocks allowed.

Parameter Priority

Parameter values changed by zaps take priority over the corresponding SSFB2C.

Parameter values set by ADARUN or ADALNK statements take priority over both values changed by zaps and values from SSFB2C.

Parameter values changed by zaps are not reported on the protocol dataset.

ADALNK Protocol Dataset

The ADALNK parameter service allows you to protocol its statements

New Messages

ADAK04 CONFIGURATION MODULE FOUND :
ADAK04 NAME : USERCONF; ASS-DATE 960229; VERSION 0130   (see note 1)
ADAK04 ENVNAME =ADATEST1    (see note 2)
ADAK04 ENVSCOPE =GLOBAL    (see note 2)
ADAK04 DBID =145    (see note 2)
ADAK04 LRVINFO =0  (see note 2)
ADAK04 DISACLOS =NO   (see note 2)
ADAK04 THE FOLLOWING ADALNx PARAMETERS ARE IN USE FOR THIS RUN
ADALNK DBID=196   (see note 3)

Notes:

  1. Information to identify a user-defined configuration module.
  2. B2CONFIG macro parameters.
  3. ADALNK parameter read from the ADALNK parameter service.
  4. Values changed by zaps are not reported.

Assembling ADALNK

The source form of ADALNK is in the Adabas source library. The procedure

/CLP ADAvsn.P,(ASM,ADALNK,LIB=USER.MOD)

—assembles the file S.ADALNK into the USER.MOD library.

The following are the selectable options available when re-assembling an Adalink module:

Option Default Action Required
LOGID 1 Specify a default logical database ID (range 1-65535)
LUINFO 0 Specify a user data length for the data passed from the ADALNK to Adabas User Exit 4.

Binding/Linking ADALNK above 16 MB

If you intend to link or bind ADALNK into contexts located above the 16-megabyte line, the ADALNK characteristics must be set to AMODE=31 and RMODE=ANY.

Top of page

Installing Adabas with Batch / TIAM

The Adalink used for batch and the TIAM TP monitor environment under BS2000 is ADALNK.

The ADALNK entry point is used where a single user issues only one Adabas call at a time and waits synchronously on the call to return. The last eight bytes (UID) of the communication ID are set to either

—where xxxx is the BS2000 task sequence number.

This Adalink is loaded by ADARUN to control multiuser (ADARUN MODE=MULTI) or utility sessions. The CSECT name is ADALNK.

ADALNK for SAPR Application Packages

The ADALNR entry point is located at offset ’xC’ in ADALNK, which is reentrant.

Calls to ADALNR require an eighth Adabas call parameter containing the address of this initialized area, which must be below the 16-megabyte line.

The seventh parameter, which is reserved for Natural applications, must always be defined. This parameter must always be used for each Adabas call.

The addressed area itself, which cannot be changed by the user, must equal the total of the two halfword counts found at ADALNK locations X’B4’ and X’B6’.

Dynamically Loading Symbols in Batch / TIAM

The binder/loader/starter (BLS) may be used to dynamically load the ADALNx (where x is K, N, Q, R, or U) or ADABAS symbol with the job statements

/SET-FILE-LINK DDLIB,<adabas_library>
.
/START-PROGRAM (MY.LIB,MYAPPL),RUN-MODE=ADVANCED(ALT-LIB=YES)
.

—where adabas_library is the name of the delivered Adabas module library.

If the program MYAPPL has the unresolved external symbol

Top of page

Installing Adabas with UTM

This section provides information required for Adabas installation with UTM.

Operation Options

UTM can operate with Adabas in two modes:

Unsynchronized Operation

UTM conforms to the KDCS (compatible data communication interface) description, which requires a TP program with the following general sequence:

  1. initialize

  2. obtain the terminal input data

  3. process the data (including any Adabas calls)

  4. write the output data to the terminal

  5. end (PEND).

Under UTM, a BS2000 task processes only a single user until PEND. By defining multiple UTM tasks for an application, requests are processed in parallel, thus improving performance.

Multiple tasks are also required to prevent deadlock situations. For example, if only one UTM task is available and user 2 requests a record held by user 1, all processing stops (deadlock) until user 2 is timed-out, thus freeing the UTM task to complete user 1’s transaction.

Running ADASAV under UTM

The Adabas utility ADASAV should only be run on a UTM system when very few update transactions are active, or deadlock can result. This occurs when fewer UTM tasks have been defined than can accommodate the number of Adabas user transactions currently open, and the ADASAV synchronization begins.

When ADASAV performs synchronization, all ET transactions are held in the command queue (CQ) until none remain to be processed. If there are more open UTM transactions than UTM tasks available, other transactions cannot be completed until the UTM transactions end; this results in deadlock.

All transactions remain frozen, waiting for time-out to occur. When the first time-out of a UTM transaction occurs, a UTM task is freed and another UTM transaction takes its place. This continues until all frozen transactions are freed, bringing synchronization to an end.

UTM Adalink Entry Points

Software AG strongly recommends that you link ADAUSER to the UTM application and that you use the ADABAS entry point.

For compatibility reasons, ADALNK may be linked to a UTM application using one of the following entry points:

Both are described as provided on the Adabas/BS2000 release tape; however, ADALNN and ADALNU defaults can be changed (zapped). While the Adabas call is being processed, the UTM task waits synchronously until the Adabas nucleus returns the call results.

ADALNN

ADALNN is used where the calling program works with different users, or must identify more than one transaction. However, only one Adabas call is processed at a time, and waits are synchronous. ADALNN is used with Natural/UTM or Natural/TIAM/MULTIPASS. The CSECT name is ADALNN. There are no additional ENTRYs.

ADALNU

ADALNU is for UTM applications that do not run with Natural. The UID part of the communication ID is set with the logical terminal ID derived from the KB header field KCLOGTER. For UTM version 3, the KB is found by the weak external KDCKB that is satisfied in KDCROOT. For older UTM versions, or in environments where ADALNU is not linked statically to KDCROOT, ADALNU locates the KB in the program’s parameter list by going back up the save area chain to the KDCROOT save area.

Linking ADAUSER to UTM Applications

Natural

Software AG recommends that you link ADAUSER to the Natural UTM application and set the Natural driver parameter.

ADACALL=NO

ADAUSER detects that UTM is the carrier system. It loads ADALNK directly and thus reads its parameters from DDLNKPAR.

COBOL or Assembler

If ADAUSER is linked to a COBOL or Assembler UTM application, ADALNK is loaded and parameters are read from DDLNKPAR.

Loading ADALNK

Whenever you link ADAUSER to UTM applications, you need to add the following link statement to the UTM start job to load the ADALNK:

/SET-FILE-LINK DDLIB,<adabas_library>

—where adabas_library is the name of the delivered Adabas module library.

Top of page