This section provides information needed to install Adabas with teleprocessing (TP) monitors TIAM and UTM.
The Adabas Version 7 application programming interface (API) comprises the modules:
ADAUSER (delivered in source)
ADAUSER2 (delivered in source)
ADALNK (delivered in source)
ADAL2P
SSFB2C (delivered in source, plus macro B2CONFIG to customize the interface)
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.
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 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:
can be made reentrant;
is small; and
has no version-specific functions. In future versions, application link jobs will not require changes. For example, the application and its linkage will not be affected if TCP/IP is used to access the database.
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.
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.
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:
If ADARUN PROGRAM=USER (the default) and ADARUN MODE=MULTI (the default), ADARUN also loads ADALNK.
If ADARUN PROGRAM=USER (the default) and ADARUN MODE=SINGLE, ADARUN also loads ADANUC.
This makes ADAUSER mode-independent.
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.
To resolve external symbols in the application module, link the following modules to it:
for ADALNx symbols, ADALNK, ADAL2P, and SSFB2C
for the ADABAS symbol, ADAUSER (note that the delivered ADAUSER is not reentrant)
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:
Insert the TSOSLNK command RENAME in the application link job to rename ADALNK before you include it:
RENAME ADALNK,ADABAS INCLUDE ADALNK,$SAG.ADABAS.MOD
To avoid changing the link job, insert the following lines behind the label ADALNU in the supplied ADALNK source in the ADAvrs.SRC library:
ENTRY ADABAS ADABAS DS 0F
Then re-assemble the ADALNK using the macros supplied in the ADAvrs.MAC library and link it to the application.
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
the file link DDCARD is present, ADARUN is loaded and these parameters are read from DDCARD. This is the traditional Adabas API.
the file link DDCARD is not present, ADALNK is loaded and these parameters are found in DDLNKPAR.
ADARUN must be loaded in order to load and install the Adabas prefetch components:
ADARUN PROG=USER,PREFETCH=YES
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
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.
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. |
The ADALNK parameter service coordinates ADARUN, ADALNK, and SSF parameters. It comprises three modules:
ADAL2P contains the parameter service routines
the ADALNK module contains the Adalink parameters
SSF2BC contains operating system specific parameters. Most of the operating system related defaults (such as the names, scopes, and sizes of memory pools, serialization and event items) are concentrated in this module.
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.
The ADALNK parameter service considers the SSFB2C configuration module:
if ADALNK is loaded by ADAUSER, SSFB2C is AUTOLINKED by V-Constant. In this case, no changes are required.
if ADALNK needs to be bound to a user program, include the following statements in the TSOSLNK JCL that links ADALNK:
... INCLUDE ADALNK INCLUDE ADAL2P INCLUDE SSFB2C or BINDER JCL : ... INCLUDE-MODULES ELEMENT=(ADALNK,ADAL2P,SSFB2C),- ...
If the INCLUDE statement for ADAL2P is omitted, an unresolved VCONS occurs and the parameter service will not be available.
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:
|
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 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.
The ADALNK parameter service allows you to protocol its statements
into SYSLST (ASS-SYSLST dataset);
into a dataset determined by “/SET-FILE-LINK DDPLNPRT,dataset” (if this link name is not included in the tasks file table, the protocol is written to SYSLST); or
nowhere. In this case, the module SSFB2C must be assembled by setting the operand ALNKPRT=NO.
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:
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. |
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.
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
Bxxxx (batch); or
Dxxxx (TIAM)
—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.
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’.
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
ADALNx, then ADALNK, ADAL2P, and SSFB2C are loaded.
ADABAS, then ADAUSER is loaded, which in turn loads ADARUN, ADAIOR, etc.
This section provides information required for Adabas installation with UTM.
UTM can operate with Adabas in two modes:
Synchronized. UTM transactions and database transactions are coordinated.
UTM is aware of database transactions and coordinates its transactions with Adabas, providing automated restart in case of failure. The selectable unit ADAUTM documented in section ADAUTM is required to implement this option.
Unsynchronized. The application completes database transactions independently of UTM.
UTM is not involved in the database transactions. Several Adabas transactions can occur within a single UTM transaction. Applications call Adabas from the ADALNK module directly. The following sections describe the process of selecting the correct UTM ADALNx entry point.
UTM conforms to the KDCS (compatible data communication interface) description, which requires a TP program with the following general sequence:
initialize
obtain the terminal input data
process the data (including any Adabas calls)
write the output data to the terminal
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.
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.
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:
ADALNN for systems running with Natural, and
ADALNU for systems running without Natural.
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 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 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.
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.
If ADAUSER is linked to a COBOL or Assembler UTM application, ADALNK is loaded and parameters are read from DDLNKPAR.
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.
