Version 7.4.4	SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

This section provides information needed to install Adabas for the teleprocessing (TP) monitors shown in the table below. Information about using Adabas with TP monitors is contained in other sections as well, particularly in the sections describing Adabas installation by operating system.

• Installing Adabas with AIM/DC

• Preparing Adabas Link Routines for IBM Platforms

• Installing Adabas with CICS

• Installing the CICS High-Performance Stub Routine

• Installing Adabas with Com-plete

• Installing Adabas with IMS

• Installing Adabas with Shadow

• Installing Adabas with Batch / TSO

Installing Adabas with AIM/DC

This section describes installation of the Fujitsu (FACOM) AIM/DC TP monitor with Adabas.

The job AIMASM is provided for assembling the source members ADALNA and ADALND, the AIM/DC-dependent link routines. You must first customize the JCL for AIMASM to select the MVS operating system MACLIB (SYS1.MACLIB) containing the LOAD macro.

Before AIMASM can be run, ADALNA must be customized to select the following options:

Note:
The modules ADALNA and ADALND are linked together to form ADALNA.

Preparing Adabas Link Routines for IBM Platforms

This section describes the preparation of Adabas link routines for TP monitors for IBM platforms.

• High-Level Assembler

• Addressing Mode Assembly Directives

• UES-Enabled Link Routines

High-Level Assembler

The IBM high-level Assembler is required when assembling the Adabas link routines for TP monitors. The high-level Assembler generates 4-digit year assembly dates into the load modules using the &SYSDATC assembly variable. The older Assemblers H and F do not support 4-digit year assembly dates.

It is possible to assemble the Adabas link routines without the high-level Assembler, either as is (ignore the assembly error), or with the &SYSDATC variable changed to yyyymmdd, any valid 4-byte unsigned decimal assembly date where yyyy is a 4-digit year, mm is a 2-digit month, and dd is a 2-digit day. The assembly date field is restricted to 4 bytes in the load module.

Addressing Mode Assembly Directives

The Adabas link routines now have AMODE and RMODE assembly directives in the source. These allow the linkage editor to produce warning messages when conflicting AMODE or RMODE linkage-editor control statements are encountered in the link JCL, JCS, or EXECs.

These assembly directives also serve to document the preferred AMODE and RMODE for each link routine. It is important to note that in and of themselves, these directives do not alter the actual addressing mode of the link routine during execution.

The batch/TSO link routine ADALNK has the following AMODE and RMODE assembly directives:

ADABAS AMODE 31
ADABAS RMODE 24

For the CICS and IMS link routines (modules LNKOLM, LNKOLSC, and ADALNI) the directives are

ADABAS AMODE 31
ADABAS RMODE ANY

Modifying the Assembly Directives

These directives may be changed by modifying the source members before assembling them, or they may be overridden by linkage editor control statements. For example, to link the batch/TSO ADALNK module with AMODE 31 and an RMODE of ANY, the following control statements may be provided as input to the linkage editor:

MODE AMODE(31),RMODE(ANY)
ENTRY ADABAS
NAME ADALNK(R)

The linkage editor control statements override the Assembler directives in the source module.

Note:
Future releases of the Adabas link routines may require an AMODE of 31 and an RMODE of ANY to function properly in the z/OS environment. Software AG strongly recommends that you evaluate application programs and update them to conform to this standard.

For more information about the AMODE and RMODE directives and their effects on the assembler, linkage editor, and execution, consult the IBM MVS/ESA Extended Addressability Guide.

UES-Enabled Link Routines

For Adabas Version 7.4, UES is enabled by default for the batch/TSO, Com-plete, and IMS link routines. It is not necessary to disable UES support. Applications that do not require UES translation continue to work properly even when the UES components are linked with the Adabas link routines. See the section Connecting UES-Enabled Databases for more information.

Disabling UES Support

However, if for some reason you feel it necessary to disable UES support in the Adabas link routines, use the following procedure to do so:

1. Edit the source member ADALCO, ADALNI, ADALNK, or ADALNKR. Set the &UES Boolean assembler variable to 0 by commenting out the source line where it is set to 1 and removing the comment from the line where it is set to 0.

2. Assemble the link routine after making any other necessary modifications to the equates and other directives in the source module as required by your installation.

3. Link the Adabas link routine and do not include any of the UES components (that is, LNKUES, ASC2EBC, or EBC2ASC).

Installing Adabas with CICS

CICS/ESA 3.2 and above for z/OS environments must run a current version of Adabas and use the command-level link component. The macro-level link routine ADALNC is no longer supported in this environment.

The Adabas command-level link routine supports the CICS transaction server (CTS) environment.

Notes:

1. The OPID option for the USERID field is not supported under CICS/ESA 3.2 and above; therefore, it is not provided with the command-level link routine.
2. When running under CICS 4.1, the CICS components from Adabas 5.3.3 or above are required.

The following sections describe specific points of Adabas/CICS installation and operation from the CICS perspective:

• Adabas Bridge for VSAM Considerations

• CICS MRO Environment Requirements

• Using CICS Storage Protection

• Standard Versus Enhanced Installation

• LNKENAB and LNKTRUE Modules

• JCL and Source Members

• Sample Resource Definitions

• Modifying Source Member Defaults (ADAGSET Macro)

• Installation Procedure

Adabas Bridge for VSAM Considerations

If you are running Adabas Bridge for VSAM 4.2 or 5.1 under CICS, you must run CICS 3.3 or above and the Adabas Version 7.1 or above command-level link routine.

Note:
Adabas Bridge for VSAM Version 4.1.1 must use the Adabas command-level link routine included in the AVB 4.1.1 source library.

CICS MRO Environment Requirements

If you run the Adabas CICS command-level link routine with the CICS multiple region option (MRO), you must set the ADAGSET option MRO=YES and use the default value for the ADAGSET NETOPT option.

You can use the ADAGSET NTGPID option to provide a 4-byte literal for the Adabas communication ID to be used by the Adabas SVC when applications that call Adabas span multiple application regions.

Alternatively, you can create a user exit B (UEXITB) for the link routine that

• sets UBFLAG1 (byte X’29’ in the UB DSECT) to a value of X’08’ (UBF1IMSR); and

• places a 4-byte alphanumeric value in the UB field UBIMSID.

The exit then allows the Adabas SVC to provide a proper Adabas communication ID in the Adabas command queue element (CQE) even when transactions originate in multiple regions.

Using CICS Storage Protection

The storage protection mechanism (STGPROT) was introduced under CICS/ESA 3.3. Storage protection permits resources to access either CICS or user storage by using the storage protection keys. Resources defined to operate in

• user key may not overwrite CICS storage, thus affording a degree of protection to CICS.

• CICS key may read or write either CICS or user key storage, affording the highest degree of access to CICS resources.

To use storage protection with Adabas, you must either

• use the task-related user exit (ADAGSET TRUE=YES); or

• define the Adabas link routine with EXECKEY(CICS) in RDO.

Software AG recommends using the task-related user exit.

Standard Versus Enhanced Installation

All supported versions of the command-level link routine can be installed using the standard installation, which comprises steps 1 through 3 of the installation procedure.

Steps 4 and 5 are required in order to use the enhanced features of the command-level link routine:

• CICS transaction isolation;

• ADASAF under CICS 4.1 or above; and

• an operationally reentrant command-level link after initialization.

Step 6 is used to install the optional DISPGWA program. The DISPGWA program is only available with the enhanced installation.

The enhanced installation is required if

• Adabas SAF Security (ADASAF) is being used under CICS 4.1 or above;

• CICS transaction isolation is used;

• Adabas Bridge for VSAM is used (Version 4.1 uses a separate command-level link routine included in the AVB Version 4.1 source library; Versions 4.2 and 5.1 use the same routine as Adabas); or

• the DISPGWA storage display program is used.

CICS Transaction Isolation

The enhanced Adabas CICS command-level link components take advantage of the transaction isolation facility provided by CICS/ESA 4.1 when running with specific hardware under z/OS.

Transaction isolation is an extension of the storage protection mechanism. It further protects CICS resources by isolating them in subspaces. This protects user key resources from one another, and protects CICS key resources from the CICS kernel.

Transaction isolation can be enabled globally through the TRANISO system initialization (SIT) parameter, and for each CICS transaction with the new resource definition ISOLATE keyword.

Transaction isolation places some restrictions on CICS resources that must be available both during the life of the CICS system and to all transactions running in the CICS system.

The Adabas CICS command-level link components must be defined to CICS with the proper storage access to ensure proper operation when transaction isolation is active:

• The Adabas CICS command-level link routine, comprising the LNKOLSC, LNKOLM, and CICS entry and exit code, must be defined to CICS as a “user key” program.

• The LNKTRUE and LNKENAB (ADATRUE and ADAENAB) programs must both be defined as “CICS key” programs.

This permits the correct degree of isolation between applications invoking the link routine and the Adabas CICS task-related user exit (TRUE), which interacts directly with CICS resources.

When CICS transaction isolation is active, user SVCs cannot execute from the CICS region. SVCs can be executed in CICS key, however, during the PLT phase of the CICS startup and termination. For this reason, the module LNKENAB is provided to execute during the PLTPI phase of CICS initialization.

ADASAF and CICS 4.1

The Adabas SAF Security (ADASAF) module resides in the Adabas nucleus region to handle the authorization of Adabas resources.

Under CICS 4.1, this module depends on the external security identifier (user sign-on) being extracted from the access control environment element (ACEE) in the caller’s address space, and being passed on to Adabas by the SVC.

Under CICS 4.1, the command-level link routine must utilize a CICS task-related user exit to extract the external security identifier from the ACEE. The Adabas task-related user exit in the module LNKTRUE has been included in Adabas for this purpose.

Note:
The Adabas task-related user exit LNKTRUE is not required for ADASAF under CICS versions prior to 4.1.

Operationally Reentrant Link Routine after Initialization

The Adabas command-level link routine is operationally reentrant and not self-modifying after initialization. During execution, a CICS global work area (GWA) is obtained and passed to the command-level link, which uses the GWA to store addresses. This feature is available for CICS Version 3.2 and above.

Note:
Do not use the JCL parameter RENT when assembling/linking the command-level link routine.

DISPGWA Module : Displaying the CICS Global Work Areas

The DISPGWA module is a program provided by Software AG as an optional feature for CICS Version 3.3 and above.

The DISPGWA program displays the global work area (GWA) used by the various command-level link components. It can be used to display other areas of CICS that are important to the Adabas command-level link routine when it is executing as a task-related user exit (TRUE). With the help of Software AG personnel, you can use this program to interrogate important data areas during problem determination.

The DISPGWA module is used only if the LNKTRUE module is used, since it is the LNKTRUE module that actually EXTRACTs the global work area.

LNKENAB and LNKTRUE Modules

This section describes the usage of the LNKENAB and LNKTRUE modules.

LNKENAB Module

The LNKENAB module

• starts and enables the task-related user exit LNKTRUE (see the next section) during PLTPI processing.

• defines the length of storage that CICS gives to LNKTRUE as each task is invoked for the first time. The storage remains in CICS until the task terminates and is used by LNKTRUE as a task work area.

• issues an Adabas command to the default target and Adabas SVC defined in the ADAGSET macro in LNKOLSC. The target need not be active.

The purpose of the command is to derive the address of the IDTH from the first SVC call. All other SVC calls from the command-level link routine are then made using a branch entry into the Adabas SVC.

LNKTRUE Module

When started and enabled by LNKENAB during PLTPI processing, the task-related user exit LNKTRUE module

• permits the command-level link routine to obtain the pointer to the access control environment element (ACEE) in a CICS/ESA 4.1 environment;

• facilitates processing when CICS transaction isolation is installed and enabled; and

• coordinates Adabas transactions through the CICS Resource Manager Interface (RMI) when the Adabas Transaction Manager (ATM) is installed and enabled.

Most of the command-level link components execute under the umbrella of LNKTRUE. This means that any abend condition during the execution of LNKTRUE is serious; CICS may even respond by terminating the entire CICS region.

Items that may cause this condition include, but are not limited to

• invalid application parameter lists for Adabas calls;

• inconsistent or incorrect keyword values coded in the ADAGSET macro for the various command-level components;

• user modification to the command-level link components or the task-related user exit; or

• incorrect coding in UEXITA and/or UEXITB components.

Software AG strongly recommends that you test application programs in a CICS region that supports the non-task-related user exit version (standard installation) of the command-level link before migrating to a task-related user exit version (enhanced installation) of the command-level link routine.

JCL and Source Members

The JCL members use the sources indicated in the following table:

Sample Resource Definitions

Under CICS/TS 1.1 and above for z/OS and VSE, the preferred method for defining and installing CICS programs and transactions is RDO (resource definition online). The CICS documentation no longer recommends the assembly of PPT and PCT entries to define resources.

The following table provides sample RDO definitions for the Adabas CICS command-level link components (SMA job number I005). The data has been extracted directly from the CICS CSD file and should be used as a guide for providing comparable information on the CEDA panels.

**********************************************************************
* Sample DEFINE control statements for the DFHCSDUP utility.
* For Adabas V7.4 CICS command-level link routine components.
*
* These control statements can be used as input to the DFHCSDUP
* CICS CSD update utility to define the Adabas CICS command-level
* link routine components on a CICS/TS system.
**********************************************************************
DEFINE PROGRAM(ADABAS) GROUP(ADABAS)
DESCRIPTION(ADABAS V74s COMMAND LEVEL LINK ROUTINE)
LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(YES) USAGE(NORMAL)
USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
EXECKEY(CICS) EXECUTIONSET(FULLAPI)
DEFINE PROGRAM(ADAENAB) GROUP(ADABAS)
DESCRIPTION(ADABAS V74s PLTPI ENABLE ADATRUE PROGRAM)
LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
EXECKEY(CICS) EXECUTIONSET(FULLAPI)
DEFINE PROGRAM(ADATEST) GROUP(ADABAS)
DESCRIPTION(ADABAS V74s DISPLAY GWA PROGRAM - DISPGWA)
LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
EXECKEY(CICS) EXECUTIONSET(FULLAPI)
DEFINE PROGRAM(ADATRUE) GROUP(ADABAS)
DESCRIPTION(ADABAS V74s TASK RELATED USER EXIT)
LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(YES) USAGE(NORMAL)
USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
EXECKEY(CICS) EXECUTIONSET(FULLAPI)
DEFINE TRANSACTION(DGWA) GROUP(ADABAS)
DESCRIPTION(TRANSACTION TO DISPLAY ADABAS GWA)
PROGRAM(ADATEST) TWASIZE(128) PROFILE(DFHCICST) STATUS(ENABLED)
TASKDATALOC(ANY) TASKDATAKEY(CICS) STORAGECLEAR(NO)
RUNAWAY(SYSTEM) SHUTDOWN(DISABLED) ISOLATE(YES) DYNAMIC(NO)
PRIORITY(1) TRANCLASS(DFHTCL00) DTIMOUT(NO) INDOUBT(BACKOUT)
RESTART(NO) SPURGE(NO) TPURGE(NO) DUMP(YES) TRACE(YES)
RESSEC(NO) CMDSEC(NO)

—where s is the system maintenance level of Adabas.

These sample DEFINE statements are located in member DEFADAC in the Adabas Version 7.4 CICS command-level source library. They can be modified and used as input to the IBM DFHCSDUP utility to define the Adabas CICS command-level components. Consult the appropriate IBM CICS documentation for information on the DFHCSDUP utility.

Modifying Source Member Defaults (ADAGSET Macro)

The ADAGSET macro is used to create default settings for the command-level link components. This macro exists in each of the installation source members. The macro settings must be identical in every installation source member used.

To facilitate the assembly of the Adabas command-level link routine components, Software AG recommends that you program the ADAGSET macro with site-specific default values and put it in a source library that is available in the SYSLIB concatenation during assembly.

It is critical that the values for the following keywords agree for all components of the Adabas CICS command-level link routine: LOGID, SVCNO, LUINFO, LRINFO, LUSAVE, NUBS, ENTPT, TRUENAM, and ENABNAM.

Step 1 of the installation procedure identifies the source members that must be edited for standard and enhanced installation.

The ADAGSET parameter options with their default values (underlined) are described below:

AVB: Adabas VSAM Bridge Support

AVB={ NO  | YES }
           

ENABNM: Entry Point Name for Program to Enable Adabas TRUE

ENABNM={ ’ADAENAB’ | ’name’ }

ENTPT: Name of the Adabas CICS Command-Level Link Routine

ENTPT={ ’ADABAS’ | ’name’ }

LADAFP: Length of Work Area for Adabas Fastpath Exit

LADAFP={ 0 | nn}

LOGID: Default Logical Database ID

LOGID= nnn

LRINFO: Length of Adabas Review Data Area

LRINFO={ 0 | 256}

LUINFO: Length of User Data passed to Adabas UEXITA and UEXITB

LUINFO={ 0 | length}

LUSAVE: Size of User Save Area for Adabas UEXITA and UEXITB

LUSAVE={ 0 | size}

LXITAA: Length of Work Area provided to UEXITA

LXITAA={ 0 | nn}

LXITBA: Length of Work Area for UEXITB

LXITBA={ 0 | nn}

MRO: Multiple Region Option

MRO={ NO | YES }

NETOPT: Method Used to Create User ID

NETOPT={ NO | YES }

NTGPID: Natural Group ID

NTGPID=4-byte-value

NUBS: Number of User Blocks Created By CICS Link Routine

NUBS={ 50 | blocks }

PARMTYP: Area for Adabas Parameter List

PARMTYP={ ALL | COM | TWA }

PURGE: Purge Transaction

PURGE={ NO | YES }

RMI: Resource Manager Interface

RMI={ NO | YES }

SAF: Adabas SAF Security

SAF={ NO | YES }

SAP: SAP Application Support

SAP={ NO | YES }

SVCNO: Adabas SVC number

SVCNO={ 0 | nnn}

TRUE: Adabas Task-Related User Exit

TRUE={ NO | YES }

TRUENM: Name of Adabas Task-Related User Exit

TRUENM= {’name’ | ADATRUE}

UBPLOC: User Block Pool Allocation

UBPLOC= {ABOVE | BELOW}

XWAIT: XWAIT Setting for CICS

XWAIT={ NO | YES }

Notes:

1. With Adabas Version 6, the default for the XWAIT parameter changed from XWAIT=NO to XWAIT=YES to conform with IBM usage.
2. If XWAIT=NO is specified, the Adabas 6.2 and above LNKOLSC module issues an EXEC CICS WAITCICS command instead of the EXEC CICS WAIT EVENT command used in previous versions. This conforms with recommended IBM usage of the WAIT and ECB lists in a high-transaction volume CICS system with CICS/ESA Version 4.1 and above.
3. All EXEC CICS commands are processed by the CICS preprocessor; the ADAGSET parameters cause the subsequent assembly step to skip some of the statements.

XWAIT Posting Mechanisms

CICS WAITCICS (XWAIT=NO) can support a “soft post” of the specified ECB. This has the disadvantage of becoming a low priority dispatchable unit of work in a CICS/ESA environment, since the “hand postable” work is not processed by CICS on every work cycle.

EXEC CICS WAIT EXTERNAL (XWAIT=YES), on the other hand, allows CICS to make use of its special post exit code, and will always be checked and processed (if posted) on every CICS work cycle.

For more details on the differences between the various CICS WAIT commands and their relationship to hard and soft posting mechanisms, consult the IBM CICS/ESA Application Programming Reference Guide and the texts accompanying IBM APAR PN39579 or “Item RTA000043874” on the IBM InfoLink service.

XWAIT and the Adabas SVC / Router

The Adabas 6.2 and above SVC is fully compatible with the XWAIT=YES setting. The SVC performs the necessary “hard post” for Adabas callers under CICS/ESA using the Adabas 6 command-level link routine. The same SVC performs a “soft post” for batch callers where the hard post is not required.

If XWAIT=YES is specified and the Adabas SVC is below the 6.2 level, a zap is required to provide the “hard post” code preferred for CICS/ESA users:

ZAP AO33024 for an Adabas 5.3.3 SVC
ZAP AO13016 for an Adabas 6.1.2 or 6.1.3 SVC

This zap is available from your Software AG technical support representative.

Software AG strongly recommends that you use the Adabas 6.2 or above SVC/router with XWAIT=YES. The zaps to earlier SVC/routers may degrade performance for non-CICS Adabas transactions that use the modified SVC/router.

Installation Procedure

• Step 1: Modify the ADAGSET Macro for the Source Member(s)
• Step 2: Modify the JCL Members
• Step 3: Install the Adabas Command-Level Link Component (SMA Job Number I070)
• Step 4: Install the Adabas Task-Related User Exit (SMA Job Number I070)
• Step 5: Install the Adabas PLT-Enable Program (SMA Job Number I070)
• Step 6: Install the DISPGWA Program (Optional)

Step 1: Modify the ADAGSET Macro for the Source Member(s)

Modify the ADAGSET macro for the source members to be used.

See the section Modifying Source Member Defaults (ADAGSET) for details. Software AG recommends that you modify a common version of ADAGSET and place it in a library available in the SYSLIB concatenation when the Adabas command-level link components are assembled.

Note:
It is no longer necessary to modify the equates inside the LNKOLSC code. Instead, use the ADAGSET macro to set default values before assembly, thus making the process easier and more self-documenting.

For the Standard Installation (Without Enhanced Functions)

Modify the source member ADAGSET to set the following options:

• database ID (LOGID);

• Adabas SVC number (SVCNO);

• any additional options necessary for your site.

For the Enhanced Installation

Modify the source member ADAGSET to set the following options:

• database ID (LOGID);

• Adabas SVC number (SVCNO);

• the command-level link routine name (ENTPT);

• the task-related user exit name (TRUENM);

• any additional options necessary for your site.

Notes:

1. It is critically important that the ENTPT and TRUENM parameters coded in the LNKENAB, LNKTRUE, and LNKOLSC modules are identical. These module names are used to identify the global work area and task-related user exit (TRUE) storage provided for the CICS transaction using the link-specific link component.
2. If you are installing multiple instances of the command-level link routine, the ENTPT and TRUENM names must be unique, as there is a one-for-one relationship between a command-level link routine, its associated task-related user exit (TRUE), and the enabling program LNKENAB run at CICS startup.

Step 2: Modify the JCL Members

Use your editor to modify the JCL members necessary for your installation, and set the library names according to your installation’s specifications. The Adabas job library contains the following JCL members:

Make mass changes to the JCL members in the following order:

Step 3: Install the Adabas Command-Level Link Component (SMA Job Number I070)

to install the Adabas command-level link component:

1. For CICCASM, concatenate the Adabas CICS 7.4 source library on the assembler SYSLIB statement in front of the Adabas source library for the version of Adabas you are running.

2. Execute CICCASM.

   This job preprocesses, assembles, and links the Adabas CICS command-level link routine modules LNKOLSC and LNKOLM into a staging load library.

   The final step of the CICCASM job links the LNKOLSC and LNKOLM modules together with CICS entry and exit code to form the Adabas command-level link routine, which is placed in a CICS RPL library.

3. Use DFHCSDUP or the CEDA RDO entry panels to add the following definition to your CICS CSD file:

   DEFINE PROGRAM(ADABAS) GROUP(ADABAS)
   DESCRIPTION(ADABAS V74s COMMAND LEVEL LINK ROUTINE)
   LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(YES) USAGE(NORMAL)
   USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
   EXECKEY(CICS) EXECUTIONSET(FULLAPI)

   —where s is the system maintenance level of Adabas.

   The Adabas command-level link routine is now installed. This completes the standard installation. To install the enhanced functions, continue with step 4.

Step 4: Install the Adabas Task-Related User Exit (SMA Job Number I070)

The Adabas CICS components reside in the Adabas CICS source library (ACI74s.SRCE).

to install the Adabas Task-Related User Exit:

1. Execute CICTASM.

   This module preprocesses, assembles, and links the Adabas task-related user exit into a staging load library, and then links it with CICS entry and exit code into a CICS RPL library.

   Unless you are following the installation procedure required for running with the Adabas Transaction Manager, expect the unresolved external references TCISYNC and TCIRESYN.

2. Use DFHCSDUP or the CEDA RDO entry panels to add the following definition to your CICS CSD file:

   DEFINE PROGRAM(ADATRUE) GROUP(ADABAS)
   DESCRIPTION(ADABAS V74s TASK RELATED USER EXIT)
   LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(YES) USAGE(NORMAL)
   USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
   EXECKEY(CICS) EXECUTIONSET(FULLAPI)

   —where s is the system maintenance level of Adabas.

Step 5: Install the Adabas PLT-Enable Program (SMA Job Number I070)

The Adabas CICS components reside in the Adabas base source library ADA74s.SRCE.

to install the Adabas PLT-enable program:

1. Execute CICEASM.

   This job preprocesses, assembles, and links this module into a staging library, and then links it with CICS entry and exit code into a CICS RPL library.

2. Use DFHCSDUP or the CEDA RDO entry panels to add the following definition to your CICS CSD file:

   DEFINE PROGRAM(ADAENAB) GROUP(ADABAS)
   DESCRIPTION(ADABAS V74s PLTPI ENABLE ADATRUE PROGRAM)
   LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
   USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
   EXECKEY(CICS) EXECUTIONSET(FULLAPI)

   —where s is the system maintenance level of Adabas.

3. After defining LNKENAB to CICS, add the following entry to your PLTPI table, DFHPLT:

   DFHPLT TYPE=ENTRY,PROGRAM=ADAENAB

   This entry should follow the first DFHPLT TYPE=DELIM statement to ensure that LNKENAB will be executed in either stage II or stage III of the CICS PLTPI process. This is necessary because the CICS EXEC interface environment must be present to support the writing of console messages using the EXEC CICS WRITE OPERATOR command employed by the LNKENAB module.

4. Code an appropriate PLTPI=xx parameter in the CICS start-up data. xx should match the suffix value given in the DFHPLT table.

Step 6: Install the DISPGWA Program (Optional)

to install the DISPGWA program:

1. Execute CICDASM.

   This job preprocesses, assembles, and links this module into a staging library, then links it with CICS entry and exit code into a CICS RPL library. The final link step creates the load module ADATEST.

2. Add a CICS transaction to execute the ADATEST program. RDO may be used to do this. Sample DEFINE statements for the ADATEST (DISPGWA) program and the transaction to execute it are:

   DEFINE PROGRAM(ADATEST) GROUP(ADABAS)
   DESCRIPTION(ADABAS V74s DISPLAY GWA PROGRAM - DISPGWA)
   LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
   USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
   EXECKEY(CICS) EXECUTIONSET(FULLAPI)
   
   DEFINE TRANSACTION(DGWA) GROUP(ADABAS)
   DESCRIPTION(TRANSACTION TO DISPLAY ADABAS GWA)
   PROGRAM(ADATEST) TWASIZE(128) PROFILE(DFHCICST) STATUS(ENABLED)
   TASKDATALOC(ANY) TASKDATAKEY(CICS) STORAGECLEAR(NO)
   RUNAWAY(SYSTEM) SHUTDOWN(DISABLED) ISOLATE(YES) DYNAMIC(NO)
   PRIORITY(1) TRANCLASS(DFHTCL00) DTIMOUT(NO) INDOUBT(BACKOUT)
   RESTART(NO) SPURGE(NO) TPURGE(NO) DUMP(YES) TRACE(YES)
   RESSEC(NO) CMDSEC(NO)

   —where s is the system maintenance level of Adabas.

   The Adabas command-level link routine, enhanced functions, and DISPGWA program are now installed.

Installing the CICS High-Performance Stub Routine

The Adabas high-performance stub routine extends the direct call interface (DCI) facility that is available with the Adabas CICS command-level link component to applications written in languages other than Software AG’s Natural (for example, Assembler, COBOL, PL/I).

Note:
The stub routine must be used with the Adabas CICS command-level link component. The stub routine will not function properly with the Adabas CICS macro-level link component.

The DCI enables a CICS/ESA 3.2 application or above to call Adabas through the Adabas command-level link routine. The overhead incurred when the EXEC CICS LINK and EXEC CICS RETURN command set is used to transfer program control is thus avoided. Once the proper environment has been established with the initial call (IC) command from the high-performance stub or Natural 3.1 or above, the DCI permits a BALR interface to be used.

The high-performance stub routine is written in Assembler language. When linked with the application program, it serves as an interface between the application and the Adabas CICS command-level link component. The application program can then issue CALL statements to access the stub routine when executing an Adabas command.

An application at CICS/ESA 3.2 level or above derives the following advantages from the high-performance stub:

• improved performance and throughput when issuing Adabas commands under CICS/ESA 3.2 or above due to the reduced use of CICS services related to the CICS LINK and RETURN program control mechanism.

• a call mechanism for Adabas requests under CICS/ESA 3.2 or above which is simpler than the methods normally employed to pass control with information from one program to another in the CICS environment.

Restrictions and Requirements

The following restrictions and requirements apply to the high-performance stub routine:

• CICS/ESA 3.2 or above Required

  The Adabas high-performance stub routine is supported under CICS/ESA 3.2 or above. Earlier versions of CICS are not supported.

  A CICS transaction work area (TWA) of at least 24 bytes must be provided to the application for the proper execution of the high-performance stub routine.

• CICS Command-Level Link Required

  The application program must be written using the CICS command-level interface and instructions, and may not issue any CICS macro level commands.

• Supported Programming Languages

  The application program may be written in ALC (Assembler language), COBOL, COBOL II, PL/I, or C. Installation verification programs (IVPs) are provided in ALC and COBOL on the distribution tape.

Additional requirements for specific programming languages are discussed later in the sections relating to each language.

Stub Components

Installation Overview

Use the following procedure to install the Adabas CICS high-performance stub routine:

• Edit, preprocess, assemble and link the LNCSTUB module.

• (Optional) Modify, preprocess, compile or assemble, link, and execute the desired installation verification program (IVP).

• Modify, preprocess, compile or assemble, link, and execute the application programs.

Step 1: Install the LNCSTUB Module

The Adabas CICS high-performance stub routine is an Assembler language module provided in source form on the distribution tape in member LNCSTUB.

Step 1 has the following substeps:

• Edit the ADAGSET macro.

• Change the LNCNAME field value, if necessary.

• Modify member JCLLNCS.

• Preprocess, assemble, and link the LNCSTUB module.

• Place the LNCSTUB load module in a library that is available to your application programs when they are linked.

Edit the ADAGSET Macro

Note:
For information about editing the ADAGSET macro, refer to the section Modifying Source Member Defaults (ADAGSET Macro).

Edit the ADAGSET macro in a library that will be available in the SYSLIB concatenation when LNCSTUB is assembled.

The values given for the ADAGSET parameters are primarily for documentation purposes within the LNCSTUB module, but may be used at a later time in the stub routine at the discretion of Software AG.

Change the LNCNAME Field Value

If your Adabas CICS command-level link component program has been linked with a name other than ADABAS, change the constant value in the field LNCNAME to match the name used (see the ADAGSET option ENTPT). The value in this field is used in the priming EXEC CICS LINK command issued by LNCSTUB.

Modify Member JCLLNCS

Member JCLLNCS is used to preprocess, assemble, and link the LNCSTUB module. To modify this JCL to meet your site requirements, change the JOB card in the member and the symbolic values as indicated in the following table:

Preprocess, Assemble, and Link the LNCSTUB Module

Because of the possible use of the 31-bit instructions, Assembler H (IEV90) or the High-Level Assembler (ASMA90) should be used to assemble the LNCSTUB module after CICS preprocessing.

Note:
The LNCSTUB module can be linked reentrant or reusable. If it is linked reentrant, it is automatically reusable; if it is linked reusable, it is not automatically reentrant.

In addition to the CICS macro library, the Adabas CICS command-level source library and standard Adabas source library must be provided to the SYSLIB DD statement in the assembly step:

• do not concatenate any CICS load libraries in the SYSLIB DD statement when linking the LNCSTUB load module.

• in the SYSLIN data stream after the LNCSTUB object deck, use just the control statement

  NAME LNCSTUB(R)

• do not include the CICS stub modules DFHEAI0 & DFHEAI1 with the LNCSTUB load module. As a result, however, the following occurs:

  • the linkage editor issues IEW462 or similar messages indicating that DFHEAI1 is an unresolved external reference;

  • the LNCSTUB module may be marked NOT EXECUTABLE by the linkage editor;

  • a condition code of 8 may be set in the link step.

  When the application program is linked with LNCSTUB, all the external references are resolved.

Make the LNCSTUB Available to Application Programs

The LNCSTUB module has an entry name of ADABAS, which can be used by the application program as the object of a CALL statement to pass control to LNCSTUB with a list of parameters. The language-specific calling conventions for LNCSTUB are discussed later in this section.

The LNCSTUB load module must be available to the link step of the application program that is to use the DCI facility.

Note:
In the same step, the CICS load library should be available; otherwise, the external references to the CICS stub modules will not be resolved.

Place the LNCSTUB load module in a library available to your application language assembler or compiler so that it will be included when the application programs are linked.

Step 2: (Optional) Install and Execute an IVP

Two installation verification programs (IVPs) are provided in source form: one for Assembler language, and one for COBOL/VS. These programs are samples for implementing the Adabas high-performance stub routine in your applications. They also provide a way of verifying the proper installation of the LNCSTUB module.

Step 2 has the following substeps:

• Modify the Assembler (ALCSIVP) or COBOL (COBSIVP) source decks to provide the proper Adabas database ID and file number on your site’s database for the Software AG-provided PERSONNEL file.

• Modify the JCL provided to preprocess and compile (assemble) the desired IVP.

• Preprocess, compile or assemble, and link the IVP using the sample JCL provided as a guide.

• Add RDO entries to your CICS system to execute the IVPs.

• Execute the IVPs to verify the LNCSTUB module (ALCSIVP and COBSIVP).

Install and Execute the Assembler IVP: ALCSIVP

The source member ALCSIVP is provided to demonstrate and verify the use of the Adabas DCI using the LNCSTUB module. This program issues a series of Adabas commands using the conventional CICS LINK/RETURN mechanism, produces a partial screen of output data, then reexecutes the same call sequence using the Adabas DCI and the LNCSTUB subprogram.

to modify source member ALCSIVP:

1. Edit the database ID and file number fields DBID (line 321) and DBFNR (line 322) to be sure they match the values needed to access the PERSONNEL file on the database you intend to use.

2. Check the fields FBUFF, SBUFF and VBUFF for values consistent with your PERSONNEL file’s FDT and data content.

3. Check the name used in the EXEC CICS LINK statement (line 242) to be sure it matches the name of your Adabas CICS command-level link component program.

to modify the JCLALCI sample job stream:

1. Member JCLALCI is used to preprocess, assemble, and link the installation verification program ALCSIVP. Place the load module in your CICS RPLLIB.

2. To modify this JCL to meet your site requirements, change the JOB card in the member and the symbolic values as indicated in the table used in step 1 (see Step 1, Modify Member JCLLNCS).

   The JCLALCI member uses one additional symbolic parameter: &CICSLIB. This is the name of your CICS RPL library.

to preprocess, assemble, and link ALCSIVP:

1. Using the modified sample JCLALCI member, preprocess, assemble, and link ALCSIVP.

to add RDO entries:

1. Add the following RDO entries to your CICS system, or use the RDO facility to add the STB1 transaction to run the ALCSIVP program:

   DEFINE PROGRAM(ALCSIVP) GROUP(ADABAS)
   DESCRIPTION(ADABAS V74s ASSEMBLER IVP FOR HIGH-PERFORMANCE STUB)
   LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
   USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
   EXECKEY(USER) EXECUTIONSET(FULLAPI)
   
   DEFINE TRANSACTION(STB1) GROUP(ADABAS)
   DESCRIPTION(TRANSACTION TO EXECUTE THE ASSEMBLER IVP FOR HIGH-PERFORMANCE STUB)
   PROGRAM(ALCSIVP) TWASIZE(32) PROFILE(DFHCICST) STATUS(ENABLED)
   TASKDATALOC(ANY) TASKDATAKEY(USER) STORAGECLEAR(NO)
   RUNAWAY(SYSTEM) SHUTDOWN(DISABLED) ISOLATE(YES) DYNAMIC(NO)
   PRIORITY(1) TRANCLASS(DFHTCL00) DTIMOUT(NO) INDOUBT(BACKOUT)
   RESTART(NO) SPURGE(NO) TPURGE(NO) DUMP(YES) TRACE(YES)
   RESSEC(NO) CMDSEC(NO)

to execute ALCSIVP:

1. Run the STB1 transaction to execute ALCSIVP. Executing ALCSIVP verifies the LNCSTUB module.

Install and Execute the COBOL IVP: COBSIVP

Member COBSIVP illustrates the use of the Adabas DCI with a COBOL program. COBIVP produces a screen showing output lines produced by a series of Adabas calls executed by the CICS LINK/RETURN facility, followed by the reexecution of these Adabas commands using the DCI.

to modify source member COBSIVP:

1. Edit the fields WORK-DBID and WORK-FNR to place the desired database ID and file number in the VALUE clauses to access the PERSONNEL file on your site’s database.

2. Ensure that the value in the field LINK-NAME matches the name used in your Adabas CICS command-level link component program.

3. Ensure that the values (literals in the PROCEDURE DIVISION) in the following fields are consistent with the requirements of the PERSONNEL file FDT and data content you are using:

   ADABAS-FORMAT-BUFFER,
   ADABAS-SEARCH-BUFFER, and
   ADABAS-VALUE-BUFFER

to modify the JCLCOBI sample job stream:

1. Member JCLCOBI is used to preprocess, compile, and link the COBSIVP installation verification program. To modify the JCLCOBI example to meet site requirements, change the JOB card in the member and provide values for the symbolic procedure variables as described in the following table:

   Value	Description
   &ADALIB	Adabas load library used to provide the ADASTWA load module for the linkage editor.
   &MEM	Member name to be processed; in this case, COBSIVP.
   &CICSLIB	CICS RPL library where the COBSIVP load module is placed for execution under CICS.
   &COBLIB	COBOL compiler STEPLIB.
   &INDEX	High-level qualifier for the CICS macro library used in the SYSLIB DD statement for the compiler.
   &INDEX2	High-level qualifier for the CICS load library to use for the translator STEPLIB DD statement, and for the SYSLIB in the link step.
   &LINKLIB	COBOL LINKLIB.
   &STBSRCE	Source library containing the distributed Adabas CICS high-performance stub LNCSTUB.
   &STUBLIB	A load library to contain the LNCSTUB load module. This library should be available to your application programs when they are linked.
   &SYSMSG	Output class for translator messages.
   &SYSOUT	Output class for SYSOUT and SYSPRINT messages.
   &WORK	DASD device type to use for temporary and utility data sets.

to preprocess, compile, and link COBSIVP:

1. Use the modified JCLCOBI job to preprocess, compile, and link the COBSIVP program. Assemble ADASTWA into a library available to COBOL programs when they are linked. Include the ADASTWA load module in the link of COBSIVP.

   COBSIVP uses the ADASTWA subroutine when it issues Adabas calls through the standard CICS LINK/RETURN mechanism. ADASTWA is supplied in source form in the Adabas source library.

   The LNCSTUB subroutine does not use ADASTWA because it places the passed Adabas parameters in the TWA. Thus, the ADASTWA routine is not required when linking COBOL applications that utilize the Adabas DCI through the LNCSTUB module.

   Even though the LNCSTUB routine does not require the ADASTWA subroutine, it is included in the COBSIVP program to illustrate the usual way in which a COBOL application places the Adabas call parameters into the CICS TWA.

2. Link the COBSIVP program with the LNCSTUB load module and the ADASTWA load module. Make the LNCSTUB load module available to the linkage editor to be included with the COBSIVP load module.

   Note:
   The CICS stub modules are also resolved in the link step.

to add RDO entries:

1. Add the following RDO entries to your CICS system, or use the RDO facility to add the STB2 transaction to run the COBSIVP program:

   DEFINE PROGRAM(COBSIVP) GROUP(ADABAS)
   DESCRIPTION(ADABAS V74s COBOL IVP FOR HIGH-PERFORMANCE STUB)
   LANGUAGE(COBOL) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
   USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
   EXECKEY(USER) EXECUTIONSET(FULLAPI)
   
   DEFINE TRANSACTION(STB2) GROUP(ADABAS)
   DESCRIPTION(TRANSACTION TO EXECUTE THE COBOL IVP FOR HIGH-PERFORMANCE STUB)
   PROGRAM(COBSIVP) TWASIZE(32) PROFILE(DFHCICST) STATUS(ENABLED)
   TASKDATALOC(ANY) TASKDATAKEY(USER) STORAGECLEAR(NO)
   RUNAWAY(SYSTEM) SHUTDOWN(DISABLED) ISOLATE(YES) DYNAMIC(NO)
   PRIORITY(1) TRANCLASS(DFHTCL00) DTIMOUT(NO) INDOUBT(BACKOUT)
   RESTART(NO) SPURGE(NO) TPURGE(NO) DUMP(YES) TRACE(YES)
   RESSEC(NO) CMDSEC(NO)

to execute COBSIVP:

1. Run the STB2 transaction to execute COBSIVP. Executing COBSIVP verifies the LNCSTUB module.

Step 3: Link and Execute the Application Program

Once the IVP programs have been successfully executed, the Adabas DCI is ready to be used with real application programs. In step 3, the application program interface (API) is coded to utilize the LNCSTUB subprogram.

Step 3 has the following substeps:

• Modify the application programs that will utilize the Adabas CICS high-performance stub routine in accordance with the guidelines described in the following section.

• Preprocess, compile or assemble, and link the application programs to include the LNCSTUB module.

• Execute the application programs using the Adabas CICS high-performance stub.

Guidelines for Modifying the Application Program

The LNCSTUB load module must be linked with your application program. The application program invokes the DCI interface using a standard batch-like call mechanism. The LNCSTUB module makes any additional CICS requests required to pass data to the Adabas CICS command-level link component.

• Programming Languages Supported by LNCSTUB

  The LNCSTUB program functions with application programs written in Assembler language, VS/COBOL, COBOL II, PL/I, and C.

• Transaction Work Area Required

  A transaction that uses the Adabas DCI or the Adabas CICS command-level link component must provide a transaction work area (TWA) at least 28 bytes long. Failure to provide an adequate TWA will result in an abend U636 (abnormal termination of the task).

• Reentrant Requirement

  The application program may or may not be reentrant. The LNCSTUB module has been written to be reentrant, but using linkage editor parameters to mark the LNCSTUB load module as reentrant is not recommended.

• CICS Requests Issued by LNCSTUB

  The LNCSTUB module issues the following command-level CICS requests whenever it is invoked:

  EXEC CICS ADDRESS TWA
  EXEC CICS ASSIGN TWALENG
  EXEC CICS ADDRESS EIB

• DCI Entry Point Address

  An EXEC CICS LINK command is issued by LNCSTUB at least once to acquire the DCI entry point from the Adabas CICS command-level link component program. This address is then used for BALR access on all subsequent Adabas calls for a transaction. Thus, the calling application program must provide a fullword (4-byte) field to hold the DCI entry point address obtained by LNCSTUB. This 4-byte field is the first parameter passed to the LNCSTUB module by the call mechanism. The remaining parameters comprise the standard Adabas parameter list needed to execute an Adabas request.

• DCI Parameter List

  The Adabas DCI parameter list expected by the LNCSTUB program is composed of a pointer to the DCI entry point in the Adabas CICS command-level link component followed by the six pointers to the Adabas control block and buffers: format, record, search, value, and ISN.

  For information on coding the standard Adabas control block and buffers, refer to the Adabas Command Reference.

  The parameter list offsets are summarized in the table below:

  Offset	Pointer to the ...
  0	DCI entry point in the Adabas command-level link component
  4	Adabas control block
  8	Adabas format buffer
  12	Adabas record buffer
  16	Adabas search buffer
  20	Adabas value buffer
  24	Adabas ISN buffer

  All of the parameters except the first (the DCI entry point) are built and maintained by the application program in accordance with the requirements of an Adabas call.

  The DCI entry point parameter should be set to binary zeros at the beginning of a task, and should not be modified by the application program thereafter. Software AG strongly recommends that the fields comprising the parameter list be placed in CICS storage (WORKING-STORAGE for COBOL and the DFHEISTG user storage area for Assembler) to maintain pseudo-reentrability.

  The following is a sample parameter list for an assembler language program:

  DFHEISTG DSECT
  .
  PARMLIST DS 0F
  DS A(DCIPTR)
  DS A(ADACB)
  DS A(ADAFB)
  DS A(ADARB)
  DS A(ADASB)
  DS A(ADAVB)
  DS A(ADAIB)
  .
  DCIPTR DS F
  ADACB DS CL80
  ADAFB DS CL50
  ADARB DS CL250
  ADASB DS CL50
  ADAVB DS CL50
  ADAIB DS CL200
  .
  DFHEIENT CODEREG=(R12),EIBREG=(R10),DATAREG=(R13)
  .
  LA R1,PARMLIST
  L R15,=V(ADABAS)
  BALR R14,R15
  .
  END

  Note:
  The DFHEIENT macro in the Assembler example uses a DATAREG parameter of register 13. This is a strict requirement of the LNCSTUB program. When the LNCSTUB program is invoked, register 13 should point to the standard CICS save area (DFHEISA) and register 1 should point to the parameter list. The best way to ensure this standard is to code the Assembler application with a DFHEIENT macro like the one in the example.

  The following is a sample parameter list for a COBOL language program:

  WORKING-STORAGE SECTION.
  .
  01 STUB-DCI-PTR PIC S9(8) COMP VALUE ZERO.
  01 ADACB PIC X(80).
  01 ADAFB PIC X(50).
  01 ADARB PIC X(250).
  01 ADASB PIC X(50).
  01 ADAVB PIC X(50).
  01 ADAIB PIC X(200).
  .
  PROCEDURE DIVISION.
  .
  CALL ’ADABAS’ USING STUB-DCI-PTR,
  ADACB,
  ADAFB,
  ADARB,
  ADASB,
  ADAVB,
  ADAIB.
  .
  EXEC CICS RETURN END-EXEC.
  .
  GOBACK.

• Restrictions on Application Program Coding

  In all other respects, the application program should be coded like a standard CICS command-level routine. As long as the DCI parameter list is correct when LNCSTUB is called, there are no restrictions on the CICS commands that an application can issue.

• Standard Batch Call Mechanism Used

  As shown in the Assembler and COBOL language program parameter list examples above, the call to ADABAS (the LNCSTUB entry point) is accomplished like a batch application. Likewise, calls for the other supported languages should be coded with their standard batch call mechanisms.

Link the Application Programs to Include the LNCSTUB Module

To properly link the LNCSTUB module with application programs, link the application program to include the LNCSTUB module and the CICS stub modules. The method for doing this varies with the programming language used for the application:

• Assembler language programs should include the DFHEAI and DFHEAI0 CICS modules;

• COBOL applications should include DFHECI and DFHEAI0.

To avoid a double reference to the DFHEAI0 module, code the linkage editor REPLACE DFHEAI0 control statement at the beginning of the SYSLIN data deck.

for linking Assembler language programs:

1. For an Assembler program, the SYSLIN input is similar to:

   INCLUDE DFHEAI

   The Assembler object input is similar to:

   REPLACE DFHEAI0
   INCLUDE SYSLIB(LNCSTUB)
   INCLUDE SYSLIB(DFHEAI0)
   NAME ALCSIVP(R)

   When examining the cross-reference from the linkage editor, the symbol “ADABAS” must have the same starting location as the LNCSTUB module in the link map.

for linking COBOL language programs:

1. For an COBOL program, the SYSLIN input is similar to:

   REPLACE DFHEAI0
   INCLUDE SYSLIB(DFHECI)

   The COBOL object input is similar to:

   INCLUDE SYSLIB(LNCSTUB)
   INCLUDE SYSLIB(DFHEAI0)
   NAME COBSIVP(R)
   

   When examining the cross-reference from the linkage editor, the symbol “ADABAS” must have the same starting location as the LNCSTUB module in the link map.

for linking PL/I and C language programs:

1. Refer to the IBM manual CICS/ESA System Definition Guide for information about linking PL/I and C applications under CICS.

Performance Using LNCSTUB

To obtain the best performance from applications using the Adabas direct call interface (DCI), examine how the DCI interface functions at the logical level.

A CICS application using the standard LINK/RETURN mechanism to access the Adabas link routines invokes the CICS program control service for every Adabas request made to the link routine. The LNCSTUB module permits a BALR interface to be used. A BALR interface can substantially reduce the CICS overhead required to pass control from the application program to the Adabas CICS command-level link component.

The LNCSTUB module accomplishes this by using the standard EXEC CICS LINK/RETURN mechanism to make an Initial Call (IC) to the Adabas CICS command-level link routine. The link routine recognizes this call, and returns the entry point address of the DCI subroutine to LNCSTUB. LNCSTUB must then save this address in a location that can be assured of existence throughout the duration of the invoking task. This is why the calling program must provide the 4-byte field to hold the DCI entry point address. After the DCI address has been obtained, and for as long as LNCSTUB receives this address as the first parameter passed to it on subsequent Adabas calls, LNCSTUB utilizes the BALR interface to pass control to the Adabas CICS command-level link component program.

As a consequence of this logic, the more Adabas requests made between ICs, the more efficient the application in terms of passing data to and from Adabas under CICS. In fact, pseudo-conversational applications that issue one Adabas call each time a task is invoked should not be coded to use the DCI because there will be an IC request for each Adabas command issued by the calling program.

An additional performance improvement can be realized by taking advantage of the fact that the Adabas CICS command-level link component program must be defined as resident in CICS. This fact should allow the DCI entry point to be stored across CICS tasks, making it possible for different programs to call the LNCSTUB module with a valid DCI entry point. The IC at each program startup is thus avoided. When this procedure is used, however, any change to the CICS environment that invalidates the entry point address (such as a NEWCOPY) will lead to unpredictable and possibly disastrous results.

It is imperative that at least one IC be made to the Adabas CICS command-level link component program using CICS services. This call is used to trigger the acquisition of shared storage for the Adabas user block (UB) and (in the case of migration aids) an array of register save areas. If no IC request is made, Adabas calls will not execute due to a lack of working storage, and to the fact that critical control blocks used by the link routines and the Adabas SVC are not built.

Installing Adabas with Com-plete

Certain Adabas parameters are required by Com-plete, Software AG’s TP monitor, when installing Adabas. For more information, see the Com-plete System Programmer’s manual.

The link routine for Com-plete initialization (module/phase ADALCO) is provided in the Adabas distribution library for the z/OS environments. ADALCO is loaded during Com-plete initialization to service Adabas calls. The Adabas library containing ADALCO should be placed in either the z/OS COMPINIT library concatenation or in the VSE/ESA LIBDEF search chain (SMA job number I070).

The Adabas Version 7.4 ADALCO is UES-enabled as distributed. See the section Connecting UES-Enabled Databases for more information.

Installing Adabas with IMS

This section describes installation of the Adabas link routine for the IMS TP monitor with Adabas.

• IMS Link Routines

• Obtaining the Adabas User ID

• Obtaining the SAF ID

• Generating a Reentrant Version

• Installation Procedure

IMS Link Routines

The Adabas link routines for IMS are:

• ADALNI for message processing programs (MPPs), and

• ADALNK the batch Adabas link routine, for batch message processing (BMP) programs, batch-oriented BMP programs, and batch processing programs (DLIBATCH).

ADALNI and ADALNK use the CSECT name and ENTRY directive ADABAS by default.

The Adabas Version 7.4 ADALNI and ADALNK are UES-enabled as distributed. See the section Connecting UES-Enabled Databases for more information.

This section describes using ADALNI only. For information on using ADALNK, read Installing Adabas with Batch / TSO.

Obtaining the Adabas User ID

The Adabas user ID is obtained at execution time by the ADALNI load module from the LTERM field (first first eight bytes) of the IOPCB. The user ID is stored in the Adabas user block field UBUID and will be used for the last eight bytes of the Adabas communication ID.

Obtaining the SAF ID

The SAF ID is supported for use by Adabas SAF Security (ADASAF) if an external security package such as IBM’s RACF or CA’s ACF2 is present. The SAF ID is obtained at execution time by the ADALNI load module from the user ID field (bytes 33-40) in the IOPCB. To get a valid user ID, signon must be active in your IMS installation and the user has performed an IMS /SIGN command to log on to an IMS terminal.

Generating a Reentrant Version

It is not recommended that a reentrant ADALNI version be generated. Please contact Software AG support if you plan to do this.

Note:
The reentrant version of ADALNI must not be used with Software AG's Natural

Installation Procedure

The following steps are required to install the Adabas IMS link routine ADALNI (SMA job number I055):

• Edit the ADALNI source member to set the assembly variables and equate values

• Assemble the ADALNI module

• Link the ADALNI module into an appropriate execution library

Step 1: Edit the ADALNI Source Member

The ADALNI source module must be edited before it can be assembled to provide the following information:

• Assembly language variables for the IMS level to be supported, and whether Adabas SAF Security (ADASAF) will be supported;

• Values for the assembler equates (EQU symbols) must be provided for the database ID (logical ID), Adabas SVC number, length of Adabas Review, and user information areas.

After modifying the assembler variables and the equate values, save your changes.

&ADAESI

A global Boolean assembly language variable, &ADAESI, is provided. Use an editor to find the SETB assembler directives in the ADALNI module and modify it to set &ADAESI as required.

If you plan to use Adabas SAF Security (ADASAF) under IMS, you must

• Set the variable &ADAESI to a 1 prior to assembling the ADALNI routine.

• Link the ADASAF exit with the Adabas router (SVC).

• Enforce all external security procedures for IMS transactions at user sign-on time.

The variable &ADAESI must be turned on (set to a "1") if ADASAF is linked with the Adabas SVC that the ADALNI module will invoke during execution.

&IMSLVL

When assembling the Adabas IMS link routine that is distributed with the Adabas source library, find the assembler local variable &IMSLVL and modify the character value in the assembler SETC directive to match the level of your IMS system: V8 or V9.

Modify Assembler Language Equates

Locate and modify the following assembly language EQU statement parameter values:

LNUINFO={user-area | 0 }

LRVINFO={work-size | 0 }

LOGID={dbid | 1 }

SVCNR={svc-number | 249 }

Step 2: Assemble the Edited ADALNI Module

Use the IBM high-level Assembler to assemble the ADALNI routine.

The order of data set concatenation on the assembly JCL SYSLIB DD statement is critically important:

Step 3: Link ADALNI for IMS

Link the ADALNI module into a library that is available in your runtime concatenation.

Specifying AMODE and RMODE

Software AG also recommends that you link the Adabas IMS link routine with AMODE of 31 and a RMODE of ANY under IMS.

The addressing mode and run mode of the Adabas link routine for IMS must be chosen to match the mode of the application programs that invoke the link routine. Since the ADALNI module will not validate the parameter addresses passed to it, it is the responsibility of the user to ensure the proper addressing (AMODE) mode.

Note:
All IMS programs that are to access Adabas should be relinked to include the Version 7.4 ADALNI module if IMS Version 3.1 or above is used at your site.

Installing Adabas with Shadow

Shadow can be used in OS/390 or z/OS and in VSE/ESA environments. The Adabas link routine specific to Shadow, ADALNS, is provided in source form along with the job SHADASM to assemble it. SHADASM must be customized to select the Shadow macro (source) library containing the macros SAVED, $WAIT, RELOCD, RETURND, TCBD.

Selecting Options for ADALNS

Customizing the source member ADALNS means selecting the following options:

Shadow Table Entry for ADALNS

The user must specify the following entry in the Shadow PCT table:

PCT PROG=ADABAS,DISP=INITL,LANG=BAL,SAVE=YES,PURGE=YES

It is important that Adabas be made resident. Under Shadow, the ADABAS parameter is normally passed in the first 24 bytes of the TWA.

The user exit called from ADALNS gains control before the Adabas call (UEXITB), and can be used to modify the eight-byte UBUID field. This allows users who process the command log to have a unique terminal, since the command log presently contains only a four-byte field. This field does not contain a unique ID. The user exit could then be used to make the first four bytes unique. The user exit must create a unique user exit for each user. For Shadow, the UBUID field normally contains the constant “SHAD” in the high-order four bytes, followed by the value from ITRMTYPE.

Installing Adabas with Batch / TSO

When installing Adabas on TSO systems, the standard Adabas batch link routine (ADALNK) provides Adabas/TSO communication (SMA job number I088).

The Adabas Version 7.4 ADALNK is UES-enabled as distributed. See the section Connecting UES-Enabled Databases for more information.

However, it is important to note that user programs linked with ADAUSER also load ADARUN. ADARUN, in turn, loads other modules.

To start a user program linked with ADAUSER, the following modules must all be available from the defined load libraries for that specific TSO user at execution time:

ADAIOR ADAMLF
ADAIOS ADAPRF
ADALNK ADARUN

ADALNKR : Reentrant Batch Link Routine

The ADALNKR source modules are provided in the Adabas source library to support applications where a reentrant batch link routine is desired. Several Software AG products require the use of the reentrant batch link routine and the ADALNKR load module is provided in the Adabas load library to support them.

Notes:

1. For Adabas 7.2.2 and above, the ADALNKR source module should be assembled separately to obtain the reentrant version of the batch/TSO link routine.
2. The ADALNKR routine differs somewhat from the nonreentrant ADALNK routine provided in the Adabas source library. It is no longer sufficient to set the &RENT Boolean variable to 1 in the ADALNK module to obtain a reentrant version which is compatible with Adabas 7.2.2 and above.
3. Software AG still recommends that batch application programs be linked with the ADAUSER module, not ADALNK or ADALNKR. The ADAUSER load module is not reentrant, but the ADALNKR module may be linked with it as long as the application program conforms to the calling requirements described below.

www.softwareag.com

Copyright © Software AG 1971-2009. All rights reserved.

SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT