Since most systems do not allow a standard call to Adabas, Software AG provides an application programming interface (API) to translate calls issued by an application program into a form that can be handled by Adabas.
Batch applications are supported in both single-user and multiuser mode; online operations are controlled by teleprocessing (TP) monitors. The Adabas API is available across all supported mainframe platforms; versions of the API that are specific to particular TP monitors are provided.
Adalink is a generic term that refers to the portion of the API that is specific to a particular TP monitor.
This document covers the following topics:
As an online operation, a request to Adabas is processed as follows:
The TP monitor invokes the application program. The application program must be loaded into the TP monitor region.
The application program invokes the Adabas API. The Adabas API module must be installed in the TP monitor as an application module.
The Adabas API takes the Adabas command passed to it from the application program and
builds the required control blocks and structures;
translates the Adabas parameter list provided by the application program call into a request that can be handled by the Adabas router or SVC;
includes information that identifies the user (terminal ID, TJID etc.) to Adabas.
The TP monitor's equivalent of the LINK function is used to pass the user's Adabas control block and buffers to the API.
The Adabas API usually uses the Adabas router or SVC (supervisor call) installed on the operating system to send the formatted request to Adabas.
The Adabas router or SVC moves the user's control block and buffers from the TP monitor region to the Adabas region (into the Adabas nucleus).
The Adabas API waits for a response from the Adabas nucleus.
The TP monitor's equivalent of a WAIT is posted when the Adabas function is complete.
Adabas performs the function requested, then invokes the Adabas router or SVC, which returns the resulting data and response codes to the user application buffer.
The Adabas router or SVC then posts the Adabas API in the TP monitor region.
The Adabas API sends the response from the Adabas nucleus to the application program and returns control to the application program.
The application program returns control to the TP monitor.
The specific way each of the above functions is handled depends on the TP monitor used. In addition to these functions, each link routine can call one or more user exits at various processing points to provide additional capability and flexibility when making Adabas requests.
The following figure illustrates the basic configuration used by the majority of systems:
As a batch operation, a request to Adabas is processed as follows:
The operating system loads the batch application.
The batch application makes an Adabas request (CALL ADABAS ...).
The Adabas stub program ADAUSER loads and invokes ADARUN, which then loads and invokes the batch Adabas link routine ADALNK.
The batch link routine transforms the Adabas request into a format suitable for use by the Adabas nucleus.
The link routine invokes Adabas, usually through a call to the Adabas router or SVC installed in the operating system. It also determines a unique identification for the user.
The link routine then waits for Adabas to handle the request.
Adabas, which is usually running in a different address space or partition, processes the request and posts the link routine, returning all necessary buffers and response codes.
The link routine receives control and returns the Adabas buffers with response codes and data to the application.
The Adabas API is available for both batch and online applications. For online applications, the Adabas API is under the control of the TP monitor. When Adabas is installed, the Adabas API that is specific to the TP monitor in use is also installed.
The following table lists the API versions and the corresponding supported TP monitors available for IBM operating environments:
Batch, TIAM and UTM all use the ADALNK API. We strongly recommend that you bind the ADAUSER module to the application or use the symbol "ADABAS" to call it, and load the ADALNK by setting the Adabas library to the link name DDLIB or in the BLSLIB library chain.
Parameters must be passed to the API. Many of the monitors do not allow standard parameter passing conventions, and the Adabas control block and buffer addresses must be moved into a special work area.
Note:
If your application program is written in Natural, the
necessary API work area is handled without change to the program code.
Adabas 8 link routines do not require that the application program obtain a work area, except if your applications make ACB interface calls to the Adabas 8 batch/TSO reentrant link routine (ADALNKR). This section describes the calling requirements peculiar to the ADALNKR routine and how applications mixing ACB and ACBX calls to the ADALNKR routine should be programmed:
Your existing Adabas 7 applications can call the Adabas 8 ADALNKR link routine without modification.
If your application makes ACB interface direct calls using the Adabas 8 batch/TSO reentrant link routine (ADALNKR), the seventh parameter must provide a four-byte fullword address that for a work area that must be initially set to binary zeros before the first call to ADALNKR. The contents of this work area should not be modified by calling application programs thereafter. The Adabas 8 ADALNKR routine uses this work area to store the reentrancy token. If this area is modified improperly, results are unpredictable and may range from poor performance to abnormal termination of the link routine.
Likewise, if your application makes ACBX interface direct calls using the Adabas 8 batch/TSO reentrant link routine (ADALNKR), the ACBX call's reentrancy token (APLXRTOK) field must initially be set to binary zeros and remain unchanged by calling application programs thereafter.
When calling ADALNKR, it is critical to mark the last parameter address in the calling parameter list with an X'80':
High-level languages do this automatically when their CALL statements are employed.
Assembler applications can do this by using the CALL macro to invoke ADALNKR.
The Adabas 8 ADALNKR routine accepts calls with the Adabas 7 parameter list with one change. To relieve the application code of the burden of obtaining the work area required by these reentrant modules, the seventh parameter should address a four-byte area initialized to binary zero, into which the ADALNKR routine will place a reentrancy token (as described earlier). This reentrancy token must remain intact between calls. If Adabas 7 and Adabas 8 calls are intermixed from the same application, this token must also be placed in the reentrancy token (APLXRTOK field) in the ACBX call.
If you provide the seventh parameter on an ACB direct call, be sure to specify the address used as the seventh parameter also in the ACBX call's reentrancy token (APLXRTOK field) to preserve user context between the logic performed by the two types of calls. Likewise, if you provide a reentrancy token on an ACBX direct call, be sure to specify the same address as the seventh parameter of the ACB direct call. If the work area address is not used in this way across ACB and ACBX direct calls, the user context for the two calling types will be different, and this could lead to incorrect results for the application.
For more information about the structure of an ACBX direct call, read Specifying an ACBX Interface Direct Call.
Note that the work area used by all Adabas 8 link routines is substantially larger than the equivalent work area used in Adabas 7. This is necessary to support the additional data structures introduced in Adabas 8 and the additional context information Adabas 8 will support.
Note:
If the Adabas 8 non-reentrant ADALNK is invoked using both
ACB and ACBX interface direct calls, the context will be preserved because the
work area is part of the ADALNK module itself.
Applications running under most TP monitors must use nonstandard calls to perform functions that are transparently handled by the operating system in a batch environment. In these cases, it is the reentrant properties of application code that determine how multiple users execute Adabas API calls online.
Each Adabas API version complies with the reentrancy requirements for its associated TP monitor. Application programs that use the Adabas API must also comply with the requirements for the TP monitor used.
Note:
The reentrancy requirement set by the TP monitor is a minimum.
For example, if the TP monitor requires a quasi-reentrant application program,
a fully reentrant program will also be accepted (see CICS special requirement
below). However, if a reentrant application program is required, a quasi- or
non-reentrant program is not acceptable.
Ideally, code for application programs that are shared by a large number of users (commonly used TP transactions) is reentrant. The code itself never changes. All work areas are either in general registers or in user-specific work areas that are addressed by general registers. A transfer of control from one user to another requires only a change in the program counter (PSW) and the general registers. Many system routines are coded in this manner.
The PL/ I compiler produces reentrant code, but by using operating system functions that are not allowed by most TP monitors. These limitations have led to the concept of quasi-reentrancy.
A quasi-reentrant program may alter its code between calls to TP monitor functions. When a monitor function is invoked, all user data must be saved in a special work area obtained from the TP monitor system. The TP monitor will then schedule another user task as the active task in the system, and this task may reuse the same code. When the original user's task becomes active again, his work area is reestablished and control is passed back to the point at which the user requested a TP monitor function.
The following subsections give more detailed information about the reentrancy requirements of several TP monitors.
Com-plete does not require nonstandard calling sequences: users may use standard non-reentrant code. Adabas linkage is provided by a Com-plete service routine, which is automatically included in the user's load module if Adabas calls are contained in the user program. The service routine simply passes the user parameters to Com-plete and returns control when the Adabas command has been executed.
The Adabas 8 CICS link routine components are fully reentrant. This is possible because the Adabas task-related user exit (TRUE) is no longer optional. Because these modules are fully reentrant, they may be loaded from LPA and the task-related user exit (TRUE), ADACICT, may be defined as thread safe to CICS. To support fully reentrant and thread safe operation and to support the larger work areas required for Adabas 8, the storage working set of these link routine components has increased. Where possible, all storage areas used by the CICS Adabas 8 components are obtained above the 16 megabyte line.
The first parameter passed to the Adabas API by the application program in an ACB interface direct call is a pointer to the Adabas control block (ACB). The ACB contains information needed to process an Adabas request.
The first byte of the ACB is used by the Adabas API to determine the processing to be performed. The values for logical requests are:
| Hex | Indicates ... |
|---|---|
| X'00' | a 1-byte file number (file numbers between 1 and 255) |
| X'30' | a 2-byte file number (file numbers between 1 and 65535) |
| X'40' | values greater than or equal to a blank. These are accepted as logical application calls to maintain compatibility with earlier releases of Adabas. The following calls, however, are reserved for use in special Software AG functions or products and are therefore not accepted: X'44', X'48', and X'4C'. |
All other values in the first byte of the ACB are reserved for use by Software AG.
This section covers the following topics:
For an application program issuing Adabas commands for file numbers between 1 and 255 (single byte), build the control block as follows:
| Position | Action |
|---|---|
| 1 | Place X'00' in the first byte of the ACB. |
| 9 | Place the file number in the second (rightmost) byte of the ACBFNR field of the ACB. The first (leftmost) byte of the ACBFNR field is used to store the logical (database) ID or number. |
If the first byte in ACBFNR is zero, the API will use either the database ID value provided in the DDCARD input data (ADARUN cards) or the default database ID value assembled into the link routine at offset X'80'. Applications written in Software AG's Natural language need not include the first byte of the ADACB because Natural supplies appropriate values.
Adabas permits the use of file numbers greater than 255 on logical requests. For an application program issuing Adabas commands for file numbers between 256 and 5000 (two-byte), build the control block as follows:
| Position | Action |
|---|---|
| 1 | Place X'30' in the first byte of the ACB. |
| 9 | Use both bytes in ACBFNR for the file number, and use the two bytes in ACBRESP for the database (logical) ID. |
If the ACBRESP field is zero, the API will use either the database ID from the ADARUN cards provided in DDCARD input data, or the default database ID value assembled into the link routine at offset X'80'.
Because the application can reset the value in the first byte of the ACB on each call, it is possible to mix both one- and two-byte file number requests in a single application.
If this method is used, you must ensure the proper construction of the ACBFNR and ACBRESP fields in the ACB for each call type.
Software AG recommends that an application written to use two-byte file numbers always place X'30' in the first byte of the ADACB, the logical ID in the ACBRESP field, and the file number in the ACBFNR field. The application can then treat both the database ID and file number as 2-byte binary integers, regardless of the value for the file number in use.
A programming language such as COBOL is not designed to easily manipulate single-byte values as required to establish two-byte file number support for the Adabas API. The following COBOL example illustrates one way to set these values:
WORKING-STORAGE SECTION
01 ACB-CONTROL
05 ACB-TYPE PIC 9(4) COMP.
05 ACB-DATA REDEFINES ACB-TYPE.
07 FILLER PIC X.
07 ACB-TYPE-X PIC X.
01 ADABAS-CB.
05 ACBTYPE PIC X.
.
PROCEDURE DIVISION
.
* FOR SINGLE-BYTE FILE NUMBERS . . .
MOVE 0 TO ACB-TYPE.
.
* FOR TWO-BYTE FILE NUMBERS . . .
MOVE 48 TO ACB-TYPE.
.
MOVE ACB-TYPE-X TO ACBTYPE.
.
CALL 'ADABAS' USING ADABAS-CB, . . .
.
.
The key to this code segment is the use of the REDEFINES clause to remap the PIC 9(4) COMP field to its constituent two bytes. Then the second byte containing the hexadecimal value for the Adabas control byte can be moved as character data to the Adabas control block.
The first parameter passed to the Adabas API by the application program in an ACBX interface direct call is a pointer to the extended Adabas control block (ACBX). The ACBX contains information needed to process an Adabas request.
The first byte of the ACBX is used by the Adabas API to determine the processing to be performed. When issuing an Adabas command, set this field to binary zeros. This indicates that a logical user call is being made (ACBXTUSR equate)
The following values in ACBXTYPE are reserved for use by Software AG and are therefore not accepted by application programs: X'04', X'08', X'0c', X'10', X'14', X'18', X'1c', X'20', X'24', X'28', X'2c', X'34', X'38', X'3c', X'44', X'48', and X'4c'.
Applications written in Software AG's Natural language need not include this first byte of the Adabas ACBX because Natural supplies appropriate values.
This section covers the following topics:
For an application program issuing Adabas commands using the ACBX interface, specify the file number in bytes 21-24 (ACBXFNR field) of the ACBX.
For a one-byte file number, enter the file number in the rightmost byte (24); the leftmost bytes (21-23), should be set to binary zeros (B'0000 0000').
For a two-byte file number, use the rightmost bytes (23-24) of the field and set the leftmost bytes (21-22) to binary zeros.
To specify the database ID of a file, use bytes 17-20 (ACBXDBID field) of the ACBX. For complete information about the layout of the ACBX, read Extended Adabas Control Block (ACBX).
For an application program issuing Adabas commands using the ACBX interface, specify the database ID in bytes 17-20 (ACBXDBID field) of the ACBX.
Specify the database ID for a call in the rightmost two bytes of this field, setting the leftmost bytes to binary zeros. At this time, only two-byte database IDs are support by Entire Net-Work.
If this field is set to binary zeros, the Adabas API uses either the database ID from the ADARUN cards provided in DDCARD input data, or the default database ID value provided in the LNKGBLS module linked with or loaded by the link routine.
If a file number is also needed, specify it in bytes 21-24 (ACBXFNR field) of the ACBX. For complete information about the layout of the ACBX, read Extended Adabas Control Block (ACBX).
This section describes the procedures used to issue Adabas calls in direct mode from a program that is to be run under the control of one of the following teleprocessing (TP) monitors:
Application programs that are to be run under control of Com-plete may be coded in exactly the same manner as batch programs. Since each application program is assigned a processing thread by Com-plete, the program need not be written using reentrant or quasi-reentrant code.
The following example shows an Adabas ACB interface direct call from a COBOL program that is to be run under Com-plete:
WORKING-STORAGE SECTION
.
.
01 CONTROL-BLOCK COPY ADACBCOB.
01 FORMAT-BUFFER COPY FORDEF.
01 RECORD-BUFFER COPY RECDEF.
01 SEARCH-BUFFER COPY SEADEF.
01 VALUE-BUFFER COPY VALDEF.
01 ISN-BUFFER COPY ISNBUF.
PROCEDURE DIVISION
.
.
.
CALL 'ADABAS' USING
CONTROL-BLOCK, FORMAT-BUFFER, RECORD-BUFFER,
SEARCH-BUFFER, VALUE-BUFFER, ISN-BUFFER.
.
Applications running under CICS use the command-level API ADACICS and the CICS Transaction Work Area (TWA) or the CICS COMMAREA to communicate parameters.
The Adabas 8 CICS link routine components accept application calls using either the TWA or the CICS COMMAREA. The COMMAREA is preferred. Software AG strongly recommends that any new CICS applications that will make ACBX interface direct calls use the COMMAREA instead of the TWA. The new ACBX direct call interface, with its variable number of Adabas buffer descriptions (ABDs) means that the Adabas parameter list length is of indeterminate size. Therefore, sizing the TWA for each transaction is more difficult using ACBX direct calls, whereas the size of the COMMAREA used is dynamically controlled by the application and is therefore better suited for ACBX calls. For information about the format of the COMMAREA, read COMMAREA Formats, later in this section.
The high-level language interface guarantees the quasi-reentrancy of COBOL, PL/ I , and Assembler (release 1.4 and above).
| Language | Control blocks and buffers may be defined ... |
|---|---|
| COBOL | in working storage. All of working storage is copied to a user work area when a transaction is initiated. |
| PL/ I | as automatic storage (default storage class) variables. |
The addresses of the Adabas control block and buffers are passed in the same way for all releases of CICS. In an ACB call, these addresses must be placed in the first six words of the TWA.
To place the ACB parameter addresses in the TWA, Software AG provides an Assembler subroutine that can be called from a COBOL or Assembler application program. The subroutine uses entry point ADASTWA and accepts the TWA as its first parameter.
The EXEC CICS ADDRESS TWA function is used to make the TWA addressable. The second to seventh parameters of an ACB call are the usual Adabas calling parameters. The Assembler subroutine places the parameter addresses into the TWA, and the CICS/Adabas link routine retrieves them from the TWA.
This section covers the following topics:
A CICS Assembler programmer can address the TWA directly by using an installation macro to place the addresses in the TWA and call Adabas.
PL/ I offers a facility for addressing the TWA and obtaining the addresses of data areas. The programmer himself can place parameter addresses in the TWA. Your site may wish to establish a PL/ I preprocessor procedure to generate the calling code.
DCL 1 TWA BASED (TWAPTR),
2 CBPTR POINTER,
2 FBPTR POINTER,
2 RBPTR POINTER,
.
EXEC CICS ADDRESS TWA (TWAPTR) END-EXEC;
.
.
CBPTR=ADDR(ADA-CONTROL-BLOCK);
FBPTR=ADDR(FORMAT-BUFFER);
RBPTR=ADDR(RECORD-BUFFER);
Under VS COBOL, Adabas is called using the statement:
EXEC CICS LINK PROGRAM ('ADABAS')
END-EXEC.
CBL XOPTS (APOST)
IDENTIFICATION DIVISION.
.
.
WORKING-STORAGE SECTION.
.
.
01 ADABAS-CB COPY ADACBCOB.
01 ADABAS-FB COPY ADAFBCOB.
01 ADABAS-RB COPY ADARBCOB.
01 ADABAS-SB COPY ADASBCOB.
01 ADABAS-VB COPY ADAVBCOB.
01 ADABAS-IB COPY ADAIBCOB.
.
.
LINKAGE SECTION.
.
.
01 PARMLIST.
05 FILLER PIC S9(08) COMP.
05 TWAPTR PIC S9(08) COMP.
01 TWA.
05 PARM-ADDRESSES OCCURS 7 TIMES PIC S9(08) COMP.
.
.
PROCEDURE DIVISION.
.
.
SERVICE RELOAD PARMLIST.
.
EXEC CICS ADDRESS TWA (TWAPTR) END-EXEC
SERVICE RELOAD TWA.
.
CALL 'ADASTWA' USING TWA, ADABAS-CB, ADABAS-FB,
ADABAS-RB, ADABAS-SB, ADABAS-VB
ADABAS-IB.
EXEC CICS LINK PROGRAM ('ADABAS') END-EXEC.
.
.
.
Under COBOL II or COBOL/LE, Adabas is called using the statement:
EXEC CICS LINK PROGRAM ('ADABAS') END-EXEC.
CBL XOPTS (APOST,ANSI85)
IDENTIFICATION DIVISION.
.
.
WORKING-STORAGE SECTION.
.
.
01 ADABAS-CB COPY ADACBCOB.
01 ADABAS-FB COPY ADAFBCOB.
01 ADABAS-RB COPY ADARBCOB.
01 ADABAS-SB COPY ADASBCOB.
01 ADABAS-VB COPY ADAVBCOB.
01 ADABAS-IB COPY ADAIBCOB.
.
.
LINKAGE SECTION.
.
01 TWA.
05 PARM-ADDRESSES OCCURS 7 TIMES PIC S9(08) COMP.
.
.
PROCEDURE DIVISION.
.
.
. EXEC CICS ADDRESS TWA (ADDRESS OF TWA) END-EXEC.
.
CALL 'ADASTWA' USING TWA, ADABAS-CB, ADABAS-FB,
ADABAS-RB, ADABAS-SB, ADABAS-VB,
ADABAS-IB.
EXEC CICS LINK PROGRAM ('ADABAS') END-EXEC.
.
.
.
Different COMMAREA formats are provided, one for Adabas 7 releases and one for Adabas 8.
The format of the Adabas 7 CICS COMMAREA, which must be at least 32 bytes long, is:
COMMID DC CL8'ADABAS52' Adabas COMMAREA ID CACBA DC A(ADACB) Address of Adabas 7 CB CAFBA DC A(ADAFB) Address of Adabas 7 FB CARBA DC A(ADARB) Address of Adabas 7 RB CASBA DC A(ADASB) Address of Adabas 7 SB CAVBA DC A(ADAVB) Address of Adabas 7 VB CAIBA DC A(ADAIB) Address of Adabas 7 IB
The layout of the Adabas 8 CICS COMMAREA is:
V8COMID DC CL8'ADABAS8X' Adabas V8 COMMAREA ID
V8APLX DS 0A Beginning of Adabas V8 APLX
V8ACBX DC A(ACBX) Adabas ADACBX
V8RSV1 DC A(0) ACBX direct call reserved field
V8APLXR DC A(0) ACBX direct call reentrancy token
V8ABD1 DC A(ABD1) First ABD
...
V8ABD#n DC A(ABD#N+X'800000') Last ABD address
IMS message processing programs that use the Adabas API require no special link. No reentrant option is supported.
The IMS link routine for Adabas 8 is ADALNI.
This section covers the following topics:
A nonreentrant Adabas API call under IMS TM is made like a conventional Adabas API call under batch as follows:
WORKING-STORAGE-SECTION.
.
.
01 ADA-CONTROL BLOCK COPY ADACBCOB.
01 FORMAT-BUFFER COPY FORDEF.
01 RECORD-BUFFER COPY RECDEF.
01 SEARCH-BUFFER COPY SEADEF.
01 VALUE-BUFFER COPY VALDEF.
01 ISN-BUFFER COPY ISNDEF.
.
PROCEDURE DIVISION.
.
.
CALL 'ADABAS' USING ADA-CONTROL-BLOCK, FORMAT-BUFFER,
RECORD-BUFFER, SEARCH-BUFFER,
VALUE-BUFFER, ISN-BUFFER.
.
.
Modern COBOL programs may use either the CICS Transaction Work Area (TWA) or the CICS Communications Area (COMMAREA) to pass data to the Adabas CICS link routines. For calls using the Adabas Version 8 API, the CICS COMMAREA is preferred because it is dynamically sized on a per call basis. The Adabas CICS high-performance stub routine (LNCSTUB) uses the CICS COMMAREA if the ADAGSET keyword PARMTYP is set to ALL or COMM.
In previous Adabas releases and with older COBOL compilers it was necessary to assemble and link-edit the Software AG-provided subprogram ADASTWA with COBOL programs to properly set the Adabas parameter addresses in the CICS Transaction Work Area.
A skeleton of such a program might have the following kinds of statements:
WORKING-STORAGE SECTION.
...
...
01 ADABAS-CB PIC X(80).
01 ADABAS-FB PIC X ...
01 ADABAS-RB PIC X ...
01 ADABAS-SB PIC X ...
01 ADABAS-VB PIC X ...
01 ADABAS-IB PIC X ...
...
...
LINKAGE SECTION.
01 PARMLIST.
05 FILLER PIC S9(08) COMP.
05 TWAPTR PIC S9(08) COMP.
01 TWA.
05 PARM-ADDRESSES OCCURS 7 TIMES PIC S9(08) C
PROCEDURE DIVISION
...
...
CALL 'ADASTWA' USING TWA,
ADABAS-CB,
ADABAS-FB,
ADABAS-RB,
ADABAS-SB,
ADABAS-VB,
ADABAS-IB.
EXEC CICS LINK PROGRAM (LINK-NAME) END-EXEC.
...
...
The use of the ADASTWA subprogram is perfectly acceptable with modern compilers but because these compilers offer a limited means for address manipulation, the above skeleton may be changed as follows to avoid the need to link the ADASTWA program with CICS COBOL applications.
WORKING-STORAGE SECTION.
...
01 TWA-LEN PIC S9(04) COMP VALUE +0.
01 ABEND-CODE PIC X(4) VALUE SPACES.
...
01 ADABAS-CB PIC X(80).
01 ADABAS-FB PIC X ...
01 ADABAS-RB PIC X ...
01 ADABAS-SB PIC X ...
01 ADABAS-VB PIC X ...
01 ADABAS-IB PIC X ...
...
...
LINKAGE SECTION.
...
01 TWA.
05 CB-PTR USAGE POINTER.
05 FB-PTR USAGE POINTER.
05 RB-PTR USAGE POINTER.
05 SB-PTR USAGE POINTER.
05 VB-PTR USAGE POINTER.
05 IB-PTR USAGE POINTER.
...
PROCEDURE DIVISION USING TWA.
...
INIT-TWA.
EXEC CICS ASSIGN TWALENG (TWA-LEN) END-EXEC.
IF TWA-LEN = 0
MOVE 'U649' TO ABEND-CODE
GO TO ...
IF TWA-LEN < 28
MOVE 'U650' to ABEND-CODE
GO TO ...
EXEC CICS ADDRESS TWA (ADDRESS OF TWA) END-EXEC.
...
SET CB-PTR TO ADDRESS OF ADABAS-CB.
SET FB-PTR TO ADDRESS OF ADABAS-FB.
SET RB-PTR TO ADDRESS OF ADABAS-RB.
SET SB-PTR TO ADDRESS OF ADABAS-SB.
SET VB-PTR TO ADDRESS OF ADABAS-VB.
SET IB-PTR TO ADDRESS OF ADABAS-IB.
...
EXEC CICS LINK PROGRAM (LINK-NAME) END-EXEC.
...
The CICS TWA size is part of the CICS transaction definition for a given set of application programs and its size may not be dynamically altered during execution of application programs running under that CICS transaction. For this reason the CICS Communications Area (COMMAREA) is recommended for Adabas Version 8 programs. The COMMAREA size may be altered as needed by the requirements of the data to be passed between programs using it. The Adabas Version 8 parameter list and data structures are dynamic in size, so the COMMAREA is the best method for passing data between CICS applications and the Adabas Version 8 CICS link routines.
Using the address manipulation features of a modern COBOL compiler, a sample skeleton of the statements needed to use the CICS COMMAREA might be:
WORKING-STORAGE SECTION.
...
...
01 ADA-COMM-AREA.
05 COMMID PIC X(8) VALUE 'ADABAS52'.
05 CB-PTR USAGE POINTER.
05 FB-PTR USAGE POINTER.
05 RB-PTR USAGE POINTER.
05 SB-PTR USAGE POINTER.
05 VB-PTR USAGE POINTER.
05 IB-PTR USAGE POINTER.
...
01 ADABAS-CB PIC X(80).
01 ADABAS-FB PIC X ...
01 ADABAS-RB PIC X ...
01 ADABAS-SB PIC X ...
01 ADABAS-VB PIC X ...
01 ADABAS-IB PIC X ...
...
01 ADA-COMM-AREA-LENGTH PIC S9(4) COMP.
...
PROCEDURE DIVISION.
...
...
INIT-ADA-COMM-AREA.
SET CB-PTR TO ADDRESS OF ADABAS-CB.
SET FB-PTR TO ADDRESS OF ADABAS-FB.
SET RB-PTR TO ADDRESS OF ADABAS-RB.
SET SB-PTR TO ADDRESS OF ADABAS-SB.
SET VB-PTR TO ADDRESS OF ADABAS-VB.
SET IB-PTR TO ADDRESS OF ADABAS-IB.
MOVE 32 TO ADA-COMM-AREA-LENGTH.
...
EXEC CICS LINK PROGRAM ('ADABAS')
COMMAREA(ADA-COMM-AREA)
LENGTH(ADA-COMM-AREA-LENGTH)
END-EXEC.
The Adabas API in batch mode uses a standard call with a parameter list in register 1 and register 13 pointing to a register save area. This convention is supported by all major programming languages through their CALL mechanisms.
Under most mainframe operating systems, the batch API (ADALNK or ADALNKR) can either be linked directly with the batch application module or it can be loaded by ADAUSER. Software AG strongly recommends that batch applications be linked with ADAUSER and not the ADALNK or ADALNKR.
The ADAUSER module can be linked with the Adabas API. ADAUSER provides upward compatibility with Adabas releases and a degree of isolation from changes that might be made in the API or the Adabas SVC in the future.
Each user program to be executed should be linked with the Adabas version-independent module ADAUSER, which dynamically loads the Adabas control module ADARUN. For batch mode execution, the user program should be linked with ADAUSER to achieve maximum environment independence, as shown below:
| User Program linked with ... | Advantage |
|---|---|
| ADAUSER, ADARUN, and ADALNK | independent of mode and Adabas version |
| ADARUN and ADALNK | independent of mode only |
| ADALNK | none; no version- or mode-independence |
The following sections illustrate the JCL/JCS required to link the batch application module with ADAUSER.
/ EXEC $TSOSLNK PROGRAM USERPROG INCLUDE USERPGM, ... User Library INCLUDE ADAUSER, ... Adabas Library END
// EXEC LKED,PARM='NCAL'
//LKED.SYSLMOD DD ... User Library
//LKED.ADALIB DD ... Adabas Library
//LKED.SYSIN DD *
INCLUDE SYSLMOD(USERPGM)
INCLUDE ADALIB(ADAUSER)
ENTRY USEREP (see note)
NAME USERPROG(R)
/*
Note:
The entry point, if specified, must be the entry point of
the user program.
* Appropriate assignments must be made for private libraries, where necessary. * // OPTION CATAL PHASE USERPROG,* INCLUDE USERPGM INCLUDE ADAUSER ENTRY USEREP (see note) // EXEC LNKEDT
Note:
The entry point, if specified, must be the entry point of
the user program.
When executing under batch, the program can be run in either single-user or multiuser mode:
Single-user mode runs the application program, the batch API, ADARUN, and the Adabas nucleus in the same address space or partition.
Multiuser mode executes the application program and the Adabas API in an address space separate from the Adabas nucleus.
The recommended mode of operation is multiuser mode. The user must provide only those job control statements required by ADARUN and the user program.
In SDF Format:
/ASS-SYSDTA *SYSCMD (ADARUN PARAMETERS) /SET-FILE-LINK DDLIB,ADAvrs.MOD /SET-FILE-LINK BLSLIB00,user modlib /START-PROGRAM USERPROG,PR-MO=ANY,RUN-MODE=ADV(ALT-LIB=YES) ADARUN MODE=MULTI...
In ISP Format:
/FILE ADABAS MODLIB,LINK=DDLIB /SYSFILE TASKLIB=user modlib /SYSFILE SYSDTA=(SYSCMD) (ADARUN PARAMETERS) /EXEC USERPROG ADARUN MODE=MULTI...
Notes:
The following example assumes that the user program USERPROG has been linked with the module ADAUSER and is to be executed in multiuser mode.
// EXEC PGM=USERPROG //STEPLIB DD ... User Library // DD ... Adabas Library //DDCARD DD * ADARUN MODE=MULTI //DDPRINT DD SYSOUT=* //... user DD statements ...
The following example assumes that the user program USERPROG has been linked with the module ADAUSER and is to be executed in multiuser mode.
//....user program assignments.... // LIBDEF PHASE,SEARCH=(user-library, ADABAS-library) // EXEC USERPROG ADARUN MODE=MULTI /*
If the user program reads statement input, one of the following applies:
If all user statements are read before the first Adabas call, they must immediately follow the EXEC statement and be followed by /*. The user file must be opened, read, and closed before the first Adabas call.
If the first Adabas call is made before the first user statement is read, the user statements must follow the ADARUN parameter statements and start with a /* statement.
Otherwise, the ADARUN parameter statements must be read from file CARD on tape or disk.
Note:
The Adabas load library must be available during execution
so that required modules can be dynamically loaded. Alternatively, only
extracts from this library can be used; in this case, the following modules
must be included: ADAIOR, ADAIOS, ADALNK (which can be adjusted to your needs),
and ADARUN. If the ADARUN parameters for multifetch or prefetch are used, the
modules ADAMLF or ADAPRF are also necessary.
In single-user mode, the appropriate Adabas nucleus JCL must be included with the JCL of the user program. This includes job control statements to define the Adabas data sets for the Associator, Data Storage, the Work data set, and any data sets for protection or command logging. For more information about Adabas runtime job control requirements, see Adabas Session Execution.
A client running under OpenEdition z/OS can access Adabas. An OpenEdition application containing calls to Adabas can be linked with ADALNK (option 1) or ADAUSER (option 2).
Software AG recommends that you link your OpenEdition application with ADAUSER (option 2) for the following reasons:
the application is not tied to a specific database ID and SVC number, or Adabas release;
the DDPRINT output provides information about the database ID and SVC number used, as well as diagnostic information in case of error (DDPRINT output is lost when using option 1); and
the program occupies less space in the hierarchical file system (HFS).
An OpenEdition application that contains calls to Adabas can be linked with the module ADALNK. The database ID and SVC number must be zapped into the Adabas CSECT of the linked module at the offsets described in section Writing User Exits for an Adalink of the Adabas Installation documentation.
The following sample ZAP and link job has the following steps:
COPYLNK: copy module ADALNK to another library
ZAPLNK: zap the copied ADALNK module
BINDAPP1: link (bind) the application with the zapped ADALNK into OpenEdition
//* //* COPY AND RENAME ADALNK //* // COPYLNK EXEC PGM=IEBCOPY //INLIB DD DSN=ADABAS.load.library,DISP=SHR //OTLIB DD DSN=ADABAS.lnk.library,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSIN DD * COPY INDD=INLIB,OUTDD=OTLIB SELECT MEMBER=((ADALNK,ADALNKOE,R)) /* //* //* ZAP DBID AND SVC INTO COPIED ADALNK //* // ZAPLNK EXEC PGM=IMASPZAP //SYSPRINT DD SYSOUT=* //SYSLIB DD DSN=ADABAS.lnk.library,DISP=SHR //SYSIN DD * NAME ADALNKOE ADABAS VER 0080 0001 DEFAULT DBID 1 VER 0084 0AF9 DEFAULT SVC 249 REP 0080 00D3 <====== CHANGE TO USER DBID (HERE DBID 211) REP 0084 0AE8 <====== CHANGE TO USER SVC (HERE SVC 232) /* //* //* BIND APPLICATION //* // BINDAPP1 EXEC PGM=IEWBLINK, // PARM='LIST,LET,XREF,MAP,CASE=MIXED' //SYSPRINT DD SYSOUT=* //SYSLMOD DD PATH='/u/group/user', // PATHOPTS=(OWRONLY,OCREAT,OTRUNC), // PATHMODE=(SIRWXU,SIRWXG,SIRWXO) //APPLIB DD DSN=your.appl.library,DISP=SHR //LNKLOAD DD DSN=ADABAS.lnk.library,DISP=SHR //SYSLIN DD * INCLUDE APPLIB(applname) INCLUDE LNKLOAD(ADALNKOE) ENTRY applent NAME oeappl(R) /*
An OpenEdition application that contains calls to Adabas can be linked with the module ADAUSER.
Additionally, a member ddcard must be set up in the OpenEdition hierarchical file system (HFS) to contain the ADARUN parameters required by the client; for example:
ADARUN PROG=USER,DBID=211,SVC=232,MODE=MULTI
Prior to the first call to Adabas, the application must set the current working directory (using the chdir() function, for example) to the directory where file ddcard is located. As the application runs, Adabas searches the current working directory for member ddcard, and extracts the parameters. Additionally, Adabas directs the DDPRINT output to member ddprint of the current working directory.
Note:
Member names ddcard
and ddprint are case-sensitive. Member
name DDCARD is not valid and will be ignored.
The following sample link job has one step:
BINDAPP2: link (bind) the application with ADAUSER into OpenEdition
//* //* BIND APPLICATION //* // BINDAPP2 EXEC PGM=IEWBLINK, // PARM='LIST,LET,XREF,MAP,CASE=MIXED' //SYSPRINT DD SYSOUT=* //SYSLMOD DD PATH='/u/group/user', // PATHOPTS=(OWRONLY,OCREAT,OTRUNC), // PATHMODE=(SIRWXU,SIRWXG,SIRWXO) //APPLIB DD DSN=your.appl.library,DISP=SHR //ADALOAD DD DSN=ADABAS.load.library,DISP=SHR //SYSLIN DD * INCLUDE APPLIB(applname) INCLUDE ADALOAD(ADAUSER) ENTRY applent NAME oeappl(R) /*
For both options, the OpenEdition shell variable STEPLIB must be set to ensure access to the Adabas load library. The following sample job sets the variable from OpenEdition running in batch mode:
//* //OEBATCH EXEC PGM=BPXBATCH, // PARM='PGM /u/group/user/oeappl' //STDIN DD PATH='/u/group/user/oeappl.in',PATHOPTS=(ORDONLY) //STDOUT DD PATH='/u/group/user/oeappl.out', // PATHOPTS=(OWRONLY,OCREAT),PATHMODE=SIRWXU //STERR DD PATH='/u/group/user/oeappl.err', // PATHOPTS=(OWRONLY,OCREAT),PATHMODE=SIRWXU //STDENV DD * STEPLIB=ADABAS.load.library /* //
Support is not available for running the following under OpenEdition:
the Adabas nucleus or utilities
clients running in single-user mode (MODE=SINGLE)
clients running in 24-bit addressing mode (AMODE 24)