This section describes how to install the ADABAS Interface in the MVS/TSO, MVS batch, and FOCUS Multi-Session Option (MSO) environments. The Interface is distributed in ready-to-execute form.
The installation process consists of the following basic tasks:
Note: The discussions in this section assume that all of your site's FOCUS and ADABAS Interface libraries are cataloged under the same MVS high-level qualifier.
The ADABAS Interface is distributed on the same tape/cartridge as the standard FOCUS product. Following are the attributes for the partitioned datasets (PDSs), or libraries, needed to use the Interface:
Dataset |
Allocation Parameters |
ADABAS.LOAD |
SPACE=(CYL,(1,1,5)), |
ADABAS.DATA |
SPACE=(CYL,(1,1,5)), |
Both of these PDSs are in IEBCOPY dump format:
To unload the distribution tape, perform these steps:
//UNLOAD EXEC PGM=IEBCOP
//SYSPRINT DD SYSOUT=*
//IN15 DD DSN=ADABAS.LOAD,DISP=OLD,
// UNIT=tape,LABEL=(15,SL,EXPDT=98000),VOL=SER=volser
//IN16 DD DSN=ADABAS.DATA,DISP=OLD,
// UNIT=tape,LABEL=(16,SL,EXPDT=98000),VOL=SER=volser
//OUT15 DD DSN=highlvl.ADABAS.LOAD,DISP=OLD
//OUT16 DD DSN=highlvl.ADABAS.DATA,DISP=OLD
//SYSIN DD *
COPY INDD=IN15,OUTDD=OUT15
COPY INDD=IN16,OUTDD=OUT16
/*
where:
Upon successful completion, two new ADABAS Interface libraries are unloaded from the tape and cataloged on your system.
The ADABAS Interface consists of the member ADBSINX in the ADABAS.LOAD library.
At execution time, FOCUS searches for the ADABAS Interface load module in the program library allocated to ddname USERLIB. If USERLIB is not allocated or if it does not contain the ADABAS Interface module, FOCUS searches in ddname STEPLIB. This search order gives the site three options:
//STEPLIB DD DSN=highlvl.FOCLIB.LOAD,DISP=SHR
// DD DSN=highlvl.ADABAS.LOAD,DISP=SHR
// DD DSN=SOFTWARE.AG.LOAD,DISP=SHR
//STEPLIB DD DSN=highlvl.FOCLIB.LOAD,DISP=SHR
// DD DSN=SOFTWARE.AG.LOAD,DISP=SHR
//STEPLIB DD DSN=highlvl.FOCLIB.LOAD,DISP=SHR
// DD DSN=SOFTWARE.AG.LOAD,DISP=SHR
//USERLIB DD DSN=highlvl.ADABAS.LOAD,DISP=SHR
All three options are roughly equivalent in overhead at execution time; the third option, however, requires a small amount of additional storage (approximately 26K) for buffers.
For interactive MVS/TSO, apply the same options. However, you cannot allocate the ddname STEPLIB dynamically using the ALLOCATE command. If you use the STEPLIB ddname online, you must allocate it in the TSO logon procedure or in your LINKLIST. The ddname USERLIB may be allocated dynamically, even within FOCUS, any time prior to the first call to the ADABAS Interface.
You need access to the Software AG load library in order for the ADABAS Interface to communicate with the ADABAS DBMS. This library, SOFTWARE.AG.LOAD, contains the ADABAS load modules and the ADABAS file named ADAUSER.
The SOFTWARE.AG.LOAD library must be included in the STEPLIB allocation or in its functional equivalent. Contact your ADABAS database administrator if you are unsure of the name of this load library at your site.
For batch mode, concatenate the SOFTWARE.AG.LOAD library with the FOCLIB.LOAD and ADABAS.LOAD libraries, or with the FOCLIB.LOAD library, in the STEPLIB allocation. See the examples in Allocating the Interface Load Modules.
For interactive MVS/TSO access, select the option appropriate for your site to access SOFTWARE.AG.LOAD:
At this point, you may need to create or modify five run-time libraries. Following sections describe how to allocate these libraries with a CLIST or batch JCL. A sample CLIST and sample batch JCL are shown in Testing the ADABAS Interface Installation.
Each Interface user must have access to the five libraries, which are described below.
The MASTER library is created when FOCUS is installed. The library is allocated to ddname MASTER, and its members are FOCUS Master Files.
FOCUS uses a Master File to describe the data in an ADABAS file. Each ADABAS file accessed by the Interface must be described to FOCUS as a Master File or as a segment in a Master File.
Using your site criteria, allocate a PDS for your Access Files as ddname FOCADBS or ACCESS. Two suggested names for this library are userid.FOCADBS.DATA or userid.ACCESS.DATA.
Note: In this appendix, we use the term FOCADBS library to refer to either the FOCADBS or ACCESS library, depending on the name chosen at your site.
Access Files correspond to Master Files and provide additional ADABAS file characteristics such as the ADABAS database number, file number, and access type.
You create and allocate your own Access File library. However, some sites create one centrally stored PDS for all Access Files. In that case, you can concatenate your individual Access Files with the site's Access Files.
The DCB requirements of the FOCADBS library are the same as those for the FOCEXEC and MASTER libraries. It must be a PDS with LRECL=80, RECFM=F or FB, and a BLKSIZE that is any multiple of 80. The amount of required space depends on the size and number of Access Files you use. Following are recommended space allocation and DCB values:
Dataset |
Allocation Parameters |
userid.FOCADBS.DATA |
SPACE=(TRK,(5,1,20)), |
For complete information about Master and Access Files, see Describing ADABAS Files to FOCUS.
The FOCEXEC library is created when FOCUS is installed. The library is allocated to ddname FOCEXEC, and its members are FOCUS procedures (FOCEXECs).
The ADABAS.LOAD library is supplied on the distribution tape. This library contains ADABAS Interface software and does not require additional preparation.
The ERRORS library is created when FOCUS is installed. Like FOCUS, the ADABAS Interface has its own set of error messages, which normally include an ADABAS response code in case of failure. The highlvl.ADABAS.DATA library contains the ADABAS Interface error messages and must be allocated to ddname ERRORS.
The following JCL concatenates the ADABAS.DATA PDS in the ERRORS allocation to properly generate ADABAS Interface error messages:
//ERRORS DD DSN=highlvl.ERRORS.DATA,DISP=SHR
// DD DSN=highlvl.ADABAS.DATA,DISP=SHR
Failure to allocate the ADABAS.DATA library properly displays the following message instead of an appropriate ADABAS Interface error message:
FOC000 ERROR MESSAGE TEXT MISSING
The number that follows FOC is the error message number. If this message displays, correct your ERRORS allocation to include highlvl.ADABAS.DATA.
For individual ADABAS Interface error messages, consult Appendix B, ADABAS Interface Error Messages. For details on the ADABAS response codes that may accompany the ADABAS Interface error messages, see your Software AG publication General Reference Set: Messages and Codes Manual.
If you use the ADABAS Interface in an MSO environment, additional steps are required:
Use the sample JCL provided in ADABAS.DATA(GENFADL) to create a new module (FADALINK) from the Software AG module ADALNK. Copy the FADALINK module into the ADABAS.LOAD library. The FADALINK module is required to identify the ADABAS SVC number to FOCUS for communication purposes.
For example:
//STEPLIB DD DSN=highlvl.FOCLIB.LOAD,DISP=SHR
// DD DSN=SOFTWARE.AG.LOAD,DISP=SHR
// DD DSN=highlvl.ADABAS.LOAD,DISP=SHR
//ERRORS DD DSN=highlvl.ERRORS.DATA,DISP=SHR
// DD DSN=highlvl.ADABAS.DATA,DISP=SHR
Optionally, include allocations for the MASTER and FOCADBS libraries in the MSO startup JCL to allow access to centrally stored Master and Access Files.
The ADABAS Interface is distributed with a full-screen, automated procedure named AUTOADBS, which simplifies the process of describing ADABAS files to FOCUS. AUTOADBS generates Master and Access Files for specified ADABAS files by using the file information cataloged in the Predict dictionary. For instructions on how to use AUTOADBS, see The AUTOADBS Facility.
The AUTOADBS installation process consists of the following tasks:
Edit the JCL found in highlvl.ADABAS.DATA(GENFADLA), using these steps:
If you use only one Predict dictionary as a source for FOCUS file descriptions, skip this section and continue with the next task (editing members in the Access File library).
For AUTOADBS to access several Predict dictionaries concurrently, you must do the following:
For example, if you have a test and production Predict dictionary, you might select T and P as the identifiers.
From: |
To: |
userid.MASTER.DATA(PREDDB) | userid.MASTER.DATA(PREDDBn) |
userid.MASTER.DATA(PREDEL) | userid.MASTER.DATA(PREDELn) |
userid.FOCADBS.DATA(PREDDB) | userid.FOCADBS.DATA(PREDDBn) |
userid.FOCADBS.DATA(PREDEL) | userid.FOCADBS.DATA(PREDELn) |
DEFAULT &DICT_FILES=' ''
and replace the blank value with the identifier.
You can have more than one character. In that case, the first character is used as the default dictionary on the AUTOADBS Main Menu. For example, if you choose P and T as your identifiers and the production dictionary is the default, the line reads:
DEFAULT &DICT_FILES='PT'
Note: The characters must be entered in uppercase.
Edit the PREDDB and PREDEL members in userid.FOCADBS.DATA (or userid.ACCESS.DATA). If you have several Predict dictionaries with associated identifiers, repeat these steps for all of the PREDDB and PREDEL members created in the FOCADBS.DATA library described in Determining Which Predict Dictionaries Require Access, in the section Installing AUTOADBS.
$ FILENAME=PREDDB,SUFFIX=ADBSINX,$
RELEASE=6,OPEN=YES,$
$ADABAS FILE = SYSDIC
SEGNAM=S02 ,ACCESS=ADBS,DBNO=001,FILENO=012,
CALLTYPE=RL,SEQFIELD=FILE_REC,
KEYFLD=FILE_ELEMENT,
IXFLD=FILE_REC
FIELD=FILE_REC ,TYPE=NOP,$
$ FILENAME=PREDEL,SUFFIX=ADBSINX,$Figure 2. Example of a PREDEL Access File
$ ADABAS FILE = SYSDIC
RELEASE=6,OPEN=YES,$
SEGNAM=S03 ,ACCESS=ADBS,DBNO=001,FILENO=012,
CALLTYPE=RL,SEQFIELD=FIELD_SEQ,$
FIELD= FIELD_SEQ ,TYPE=SPR,$
FIELD=FILE_NAME_EL ,TYPE= ,NU=NO,$
FIELD=FIELD_SEQUEN ,TYPE=DSC,NU=NO,$
SEGNAM=BD0103,ACCESS=MU ,DBNO=001,FILENO=012,$ COMMENTS
SEGNAM=BQ0603,ACCESS=MU ,DBNO=001,FILENO=012,$ DERIVATION_GROUP
The PASSWORD attribute with the value ADADBA is included in the following sample PREDEL Access File:
$ FILENAME=PREDEL,SUFFIX=ADBSINX,$
$ ADABAS FILE = SYSDIC
RELEASE=6,OPEN=YES,$
SEGNAM=S03 ,ACCESS=ADBS,DBNO=001,FILENO=012,PASSWORD=ADADBA,
CALLTYPE=RL,SEQFIELD=FIELD_SEQ,$Figure 3. Example of a PREDEL Access File With the PASSWORD Attribute
FIELD= FIELD_SEQ ,TYPE=SPR,$
FIELD=FILE_NAME_EL ,TYPE= ,NU=NO,$
FIELD=FIELD_SEQUEN ,TYPE=DSC,NU=NO,$
SEGNAM=BD0103,ACCESS=MU ,DBNO=001,FILENO=012,PASSWORD=ADADBA,$ COMMENTS
SEGNAM=BQ0603,ACCESS=MU ,DBNO=001,FILENO=012,PASSWORD=ADADBA,$
Determine how AUTOADBS treats the CALLTYPE value you supply. The CALLTYPE attribute appears in all generated Access Files. Its value indicates whether the ADABAS Interface needs to construct Read Logical (RL) or FIND calls for retrieval. You have two choices:
DEFAULT &REQ_RL=NO
Change NO to YES. If you do this, AUTOADBS will accept only the RL value.
We recommend using the SEQFIELD option. This field (an index) is used when there are no IF or WHERE clauses in the report request. This option avoids an L2 call (read physical) through the entire database. Using the index is more efficient in most cases.
Determine if AUTOADBS requires the SEQFIELD value. The SEQFIELD attribute is specified to use an ADABAS descriptor or superdescriptor's inverted list for retrieval by default. You have two choices:
DEFAULT &REQ_SEQFIELD=YES
Change YES to NO. If the user chooses to specify a SEQFIELD value when running AUTOADBS, AUTOADBS will include the value in the generated Access File. However, a value is not required.
AUTOADBS displays default output dataset names for the Master File, Access File, and FOCDEF file. These defaults follow standard IBI naming conventions. The defaults are changed on a per-user basis by replacing the values on the screen and then logging them to disk for subsequent use. Alternatively, the AUTOADBS FOCEXEC can be modified to include site-specific naming conventions for all users.
To customize the initial dataset defaults for all users, edit the following lines in the AUTOADBS member of userid.FOCEXEC.DATA. Change the expression on the right-hand side of the equal sign as appropriate. The resulting expression must retain a length of 44 characters (&USERID accounts for eight characters). You only need to customize the following lines
SET &DSNP0=&USERID ||'.FOCADBS.DATA ';
SET &DSNM0=&USERID ||'.MASTER.DATA ';
SET &DSNF0=&USERID ||'.FOCADBS.DATA ';
SET &DSND0=&USERID ||'.FOCDEF.DATA ';
where:
To test the ADABAS Interface installation and file descriptions used by AUTOADBS, use the following samples and FOCUS report request. Modify them according to your site's requirements. You may need to change the dataset name for the ADARUN parameter file. (See Using the DDCARD ddname to Specify Site Defaults.)
Specify your site information and execute the following CLIST
/*****************************************************************************/
/* *Test CLIST FOR testing FOCUS w/ ADABAS Interface* */
/* Note: This CLIST assumes that the Software AG load library has been */
/* allocated to ddname STEPLIB in the TSO logon proc or system linklist. */
/* 'highlvl' represents the high
level qualifier chosen for the */
/* FOCUS libraries. */
/*****************************************************************************/
/* */
/* Allocate FUSELIB.LOAD and ADABAS.LOAD to ddname USERLIB */
/* */
ALLOC F(USERLIB) DA('highlvl.FUSELIB.LOAD'
'highlvl.ADABAS.LOAD') SHR REU
/* Allocate ddnames that will be used in the FOCUS session. */
/* Assure that the PDSes allocated to FOCEXEC, MASTER, and */
/* FOCADBS are the ones that contains the AUTOADBS files copied */
/* in the AUTOADBS Installation step. */
/* */
ALLOC F(ERRORS) DA('highlvl.ERRORS.DATA'
'highlvl.ADABAS.DATA') SHR REUSE
ALLOC F(FOCEXEC) DA('userid.FOCEXEC.DATA') SHR REUSE
ALLOC F(DDCARD) DA('SOFTWARE.AG.ADARUN') SHR REUSE
ALLOC F(MASTER) DA('userid.MASTER.DATA') SHR REUSE
ALLOC F(FOCADBS) DA('userid.FOCADBS.DATA') SHR REUSE
/* The actual call to the FOCUS module follows */
CALL 'highlvl.FOCLIB.LOAD(FOCUS)'
where:
The result is a FOCUS session in interactive MVS/TSO. Once in FOCUS, enter this simple report request:
TABLE FILE PREDDB
PRINT FILE_ELEMENT
IF RECORDLIMIT EQ 10
END
If the ADABAS Interface is properly installed, the result is a FOCUS report that displays data from the first ten records in your Predict dictionary.
Note: If you customize AUTOADBS to run with multiple copies of the Predict dictionary, append the suffix for the identifier to PREDDB in the request. For example, if you choose P or T as a suffix, specify
TABLE FILE PREDDBP
or:
TABLE FILE PREDDBT
If you do not receive a report (0 records), make sure that the Predict dictionary contains data. The Predict dictionary is identified by the DBNO and FILENO in FOCADBS.DATA(PREDDB) and FOCADBS.DATA(PREDEL).
If you receive any ADABAS Interface error messages and/or ADABAS response codes, check your installation against the instructions in this appendix. Also consult Interface Error Messages, and the appropriate Software AG documentation, or call Information Builders for assistance.
Specify your site information and submit the following job:
//* * * * * JOB CARD Information goes here * * * * *
//*Note that 'highlvl' represents the high
level qualifier chosen for
//the FOCUS libraries. For the ddnames MASTER, FOCADBS, and FOCEXEC,
//make certain that you are pointing to the libraries that contain
//the files used by AUTOADBS as described above.
//STEP01 EXEC PGM=FOCUS
//STEPLIB DD DSN=SOFTWARE.AG.LOAD,DISP=SHR *The ADABAS load library*
// DD DSN=highlvl.FOCLIB.LOAD,DISP=SHR
// DD DSN=highlvl.ADABAS.LOAD,DISP=SHR
//USERLIB DD DSN=highlvl.FUSELIB.LOAD,DISP=SHR
//ERRORS DD DSN=highlvl.ERRORS.DATA,DISP=SHR
// DD DSN=highlvl.ADABAS.DATA,DISP=SHR
//FOCEXEC DD DSN=userid.FOCEXEC.DATA,DISP=SHR
//MASTER DD DSN=userid.MASTER.DATA,DISP=SHR
//FOCADBS DD DSN=userid.FOCADBS.DATA,DISP=SHR
//DDCARD DD DSN=SOFTWARE.AG.ADARUN,DISP=SHR
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
TABLE FILE PREDDB
PRINT FILE_ELEMENT
IF RECORDLIMIT EQ 10
//
where:
If the ADABAS Interface is properly installed, the result is a FOCUS report that displays data from the first ten records in your Predict dictionary.
Note: If you customize AUTOADBS to run with multiple copies of the Predict dictionary, append the suffix for the identifier to PREDDB in the request. For example, if you choose P or T as a suffix, specify
TABLE FILE PREDDBP
or:
TABLE FILE PREDDBT
If you do not receive a report (0 records), make sure that the Predict dictionary contains data. The Predict dictionary is identified by the DBNO and FILENO in FOCADBS.DATA(PREDDB) and FOCADBS.DATA(PREDEL).
If you receive any ADABAS Interface error messages and/or ADABAS response codes, check your installation against the instructions in this appendix. Also consult Appendix B, Interface Error Messages, and the appropriate Software AG documentation, or call Information Builders for assistance.
| Information Builders |