Connecting to UES-Enabled Adabas Databases

Prior to Adabas version 7, Entire Net-Work converted all data for mainframe Adabas when necessary from ASCII to EBCDIC. Starting with version 7, Adabas is delivered with its own data conversion capability (module LNKUES); that is, Universal Encoding Support (UES). Entire Net-Work detects when it is connected to a target database with UES support and passes the data through to Adabas without converting it.

In order for UES support to work, various ADALNK modules must be linked to the Adabas UES module, LNKUES. LNKUES converts data in the Adabas buffers and byte swaps, if necessary, depending on the data architecture of the caller. All currently supported versions of Adabas provide a UES-enabled ADALNK module; so there is nothing you need to do for UES support. However, if you have altered the translation table, you will need to assemble and link the ADALNK module again.

Important:
If an ADALNK batch link routine has been linked or modified by Software AG product modules or user exits, it cannot be used in any application startups of Adabas utility jobs or Adabas, Entire System Server, Adabas Review Hub, or Entire Net-Work nuclei.

This document covers the following topics:


Overview of UES Support

This section provides a general overview of the UES support provided in Adabas. For detailed information about UES support in Adabas, refer to the Adabas installation documentation for the operating system you are using.

In order for UES support to work, various ADALNK modules and tables must be linked to the Adabas UES module, LNKUES. LNKUES converts data in the Adabas buffers and byte-swaps, if necessary, depending on the data architecture of the caller.

This section covers the following topics:

UES-Linked Load Modules

The ADALNK load modules that have been linked with module LNKUES vary, depending on the operating system and environment you are running. For a complete list of the modules that have been linked, read the UES sections of the appropriate Adabas installation documentation.

UES Translation Tables

Two standard translation tables are provided with Adabas UES support:

  • ASC2EBC: ASCII to EBCDIC translation

  • EBC2ASC: EBCDIC to ASCII translation

The Adabas and Entire Net-Work translation table pairs are provided in the appropriate Adabas installation documentation.

You can use the supplied translation tables, or you may prepare your own customized translation tables, reassemble them , and link them with the LNKUES module. Using your own customized translation tables should only be necessary if you require the use of some country-specific character other than the standard A-Z, a-z, or 0-9 characters in the additions 1 (user ID) or additions 3 field of the control block. For detailed information on using the default or customized translation tables, refer to the UES sections of the appropriate Adabas installation documentation.

If you prefer to use the same translation tables that are used in Entire Net-work, change the COPY statements in ASC2EBC and EBC2ASC from UES2ASC and UES2EBC to NW2ASC and NW2EBC, respectively. After modifying the translation tables, be sure to (re)assemble them and link them with the delivered LNKUES module. The sample jobs referenced in Connecting to UES-Enabled Databases through Entire Net-Work and Connecting to a UES-Enabled Database through ADATCP include steps that reassemble and link the translation tables with LNKUES.

Job Steps

Job library members are provided with Adabas for each operating system it supports to assemble and link the appropriate modules with the UES components. For more information, read the UES sections of the appropriate Adabas installation documentation.

Calling LNKUES

On all platforms, LNKUES receives control before UEXITB for UES requests and after UEXITA for UES replies.

Connection Possibilities

UES-enabled databases are connected to machines with different architectures through Entire Net-Work and optionally through ADATCP -- a direct TCP/IP link to the Adabas nucleus from web-based applications such as Software AG's Jadabas. These connection methods are described elsewhere in this section.

Environment Requirements

To support UES-enabled databases, be sure that your environment meets the requirements described in this section.

Database Requirements

The Adabas database must be UES-enabled (it must have been defined with UES=YES set during the ADADEF utility run). For complete information read about database maintenance tasks in the Adabas DBA tasks documentation and about the ADACMP and the ADADEF utilities in the Adabas utilities documentation.

Start of instruction setIn general, to UES-enable an Adabas database:

  • Specify MODIFY UES=YES in the Adabas ADADEF utility settings for each target database.

Data Set Requirements

Make sure that the internal product libraries described in this section are loaded and concatenated correctly.

Required Internal Product Libraries

Software AG internal product libraries that are required if you intend to enable a database for universal encoding service (UES) support are now delivered separately from the product libraries. For UES support, the following libraries must be loaded and included in the STEPLIB or LIBDEF concatenation:

APS272.MVSLDnn

where nn is the load library level. If the library with a higher level number is not a full replacement for the lower level load library(s), the library with the higher level must precede those with lower numbers in the steplib concatenation.

Also for UES support, the following library must be loaded and included in the session execution JCL:

ADABAS.Vvrs.ADAvrs.MVSEC0n 

This library includes all supported code pages. For more information about the supported code pages, read about Supplied UES Encodings in your Adabas documentation.

Adabas JCL Updates

If you intend to enable your database for universal encoding service (UES), the startup job for the Adabas nucleus must be updated as described in this section.

  • The MVSLDnn internal product libraries must be concatenated in the STEPLIB or LIBDEF. The following is an example of such a STEPLIB concatenation:

    //STEPLIB DD DISP=SHR,DSN=ADABAS.Vvrs.ADAvrs.MVSLOAD
    //        DD DISP=SHR,DSN=ADABAS.Vvrs.APSvrs.MVSLDnn

    where nn is the load library level. If the library with a higher level number is not a full replacement for the lower level load library(s), the library with the higher level must precede those with lower numbers in the steplib concatenation.

  • If you intend to connect your UES-enabled database directly through ADATCP, the ADATCP library must also be concatenated in the STEPLIB. The following example shows a sample DD statement in a STEPLIB concatenation:

    //DD DISP=SHR,DSN=SAG.WCPvrs.MVSLOAD
    //DD DISP=SHR,DSN=SAG.WTCvrs.MVSLOAD
  • Also for UES support, the following ECS objects data set must be loaded and included in the session execution JCL:

    //DDECSOJ DD DISP=SHR,DSN=ADABAS.Vvrs.ADAvrs.MVSEC0n 

    Note:
    The data set DDECSMF (messages) previously required for UES support no longer exists and reference to it needs to be deleted from your JCL. Likewise, the CONFIG DD "dummy" data set is no longer needed.

Disk Space Requirements for Internal Product Data Sets

The minimum disk space requirements on a 3390 disk for the internal product libraries delivered with Adabas is as follows:

Libraries 3390 Cylinders 3390 Tracks Directory Blocks
APS272.MVSLD00 6 86 100

SYSPARM Requirements

To support UES, you need to add SYSPARM statements and parameters to your session execution JCL, as follows:

//SYSPARM DD*
SYSTEM_ID=ADAAPS
ABEND_RECOVERY=NO
THREAD_ABEND_RECOVERY=NO

These SYSPARM statements and parameters are required for the APS internal product.

If you are using the ADATCP component with UES support, you will need an additional parameter, CDI_DRIVER, to identify the TCP/IP stack you are using, as follows:

CDI_DRIVER=('tcpip,PAAOSOCK,ADDRSPCE=STACKNAME') <--IBM TCP/IP stack for OES

Verify Required ADALNK Module Available

Ensure that the ADALNK module in Entire Net-Work's STEPLIB or LIBDEF is UES-enabled. ADALNK is UES-enabled by default. WAL Version 8 (or later) is included with Entire Net-Work Version 3.

Connecting to UES-Enabled Databases through Entire Net-Work

The ADALNK module has been UES-enabled for you, so there are no specific steps you must perform to connect to UES-enabled databases. However, if you have altered the translation tables, you will need to perform the step described in this section (depending on the platform) that assembles and links the updated translation tables into ADALNK.

In all cases, whenever you alter ADALNK, you must be sure to make the updated module available to Entire Net-Work.

Assembling and Linking ADALNK on z/OS Systems

Start of instruction setTo assemble and link the ADALNK module on z/OS systems:

  1. Assemble and link the modified batch ADALNK with the translation tables and LNKUES. You can use the sample JCL found in MVSJOBS member ALNKLNK7 in the WAL libraries. Make sure you:

    • Provide all necessary job card information.

    • Check the symbolic parameter value for version, revision level, and SP level (vrs). It must reflect the level of your Adabas source and load libraries.

    • Check the data set names for SYSLIB, SYSIN, SYSLMOD, and SYSLIN in the SAGASM and LINKALL inline procedures.

  2. Once it is successfully linked, make ADALNK available to Entire Net-Work's job STEPLIB concatenation list.

For complete instructions on UES-enablement in Adabas, refer to the UES sections of your Adabas documentation.

Assembling and Linking ADALNK on z/VSE Systems

Start of instruction setTo assemble and link the ADALNK module on z/VSE systems:

  1. Assemble and link ADALNK with LNKUES and the translation tables into a separate sublibrary for use with UES only (this is sample job ALNKLNK8.X in the Adabas or WAL library). Otherwise, you can use the following sample JCS:

    // OPTION CATAL,LIST                                     
    // EXEC PROC=ADAVVLIB                                    
    // LIBDEF OBJ,SEARCH=(ADALIB.ADAVRS)                     
    // LIBDEF PHASE,CATALOG=ADALIB.ADAVRS                    
     PHASE ADALNK,*,NOAUTO                                   
     MODE AMODE(31),RMODE(24)                                
     INCLUDE LNKVSE8                                         
     INCLUDE LNKIND                                          
     INCLUDE LNKUES                                          
     INCLUDE LNKDSL                                          
     INCLUDE RTRVSE                                          
     INCLUDE ASC2EBC                                         
     INCLUDE EBC2ASC                                         
     INCLUDE LNKGBLS                                         
     ENTRY ADABAS                                            
    // EXEC LNKEDT,PARM='MSHP'
  2. Once it is successfully (re)linked, make ADALNK available to Entire Net-Work's job LIBDEF concatenation list. If you are calling Adabas version 7 and you do not have the correct LNKUES/ADALNK module, Adabas produces unexpected results: response code 022 (ADARSP022), 253 (ADARSP253), etc.

For complete instructions on UES-enablement in Adabas, refer to the UES sections of your Adabas documentation.

Assembling and Linking ADALNK on BS2000 Systems

Start of instruction setTo assemble and link the ADALNK module on BS2000 systems:

  • Link or bind LNKUES, ASC2EBC and EBC2ASC to the ADALNK module.

    The following sample JCL takes modules from $SAG.ADABAS.MOD and makes a new ADALNK module with LNKUES and the translation tables (ASC2EBC and EBC2ASC) in $SAG.ADABAS.ADALNKUES.MOD:

    /BEGIN-PROC A,PROC-PAR=(-                     
    / &ADAL=$SAG.ADABAS.ADALNKUES.MOD,-                 
    / &ADAS=$SAG.ADABAS.MOD,-                 
    / &LIB=$SAG.ADABAS.PROTOCOL,-                  
    / &MEM­ALNK,-                               
    / &MOD­ALNK-                                
    / ),ESC-CHAR=’&’                              
    /REMA                                         
    /REMA                                         
    /REMA                                         
    /MOD-TEST DUMP=NO                             
    /ASS-SYSLST *L(&LIB,LNK.&MEM)                 
    /ASS-SYSDTA *SYSCMD                           
    /REMA                                         
    /STA-PROG $TSOSLNK                            
    MOD &MOD,LET=Y,LIB=&ADAL,XREF=Y,PR=Y,SORT=Y   
    NCAL                                          
    TRAITS AMODE=ANY,RMODE=ANY                    
    LINK-SYMBOLS HIDE=LNKUES       
    INCLUDE &MEM,&ADAS             
    INCLUDE LNKUES,&ADAS
    INCLUDE ASC2EBC,&ADAS
    INCLUDE EBC2ASC,&ADAS           
    BIND                           
    /ASS-SYSLST *PRIM              
    /ASS-SYSDTA *PRIM              
    /END-PROC            

For complete instructions on UES-enablement in Adabas, refer to the UES sections of your Adabas documentation.

Connecting to a UES-Enabled Database through ADATCP

To connect to a UES-enabled database through ADATCP (the direct TCP/IP link), you must:

  • Update the ADALNK LNKGBLS table so it identifies the SVC number that ADATCP should use. This is described in Step 1 below.

  • Ensure that the database has been UES-enabled. This is accomplished by updates to the ADALNK module. By default, the Adabas ADALNK module has been UES-enabled for you. However, if your site has altered this or if you have altered the translation tables, you will need to make the updates described in Step 2 below and in Connecting to UES-Enabled Databases through Entire Net-Work.

    Whenever you alter ADALNK, you must be sure to make the updated module available to Entire Net-Work. This is described in Step 3 below.

  • Verify that you are using the correct libraries in your STEPLIB concatenation and that appropriate zaps have been applied. This is described in Step 4 below.

Once you have completed these steps, you should activate the TCP/IP link, as described in Activating the TCP/IP Link.

1. Prepare a modified batch ADALNK.

Update the source LNKGBLS table as follows:

SVCNO=nnn,         Default Adabas SVC number 

where nnn is the SVC number on which the system is to run.

2. Assemble and link ADALNK with the translation tables and LNKUES

This can be performed by tailoring the supplied jobs ASMGBLS and ALNKUES. Make sure you:

  • Provide all necessary job card information.

  • Check the symbolic parameter value for version, revision level, and SP level (vr SP sp). It must reflect the level of your Adabas source and load libraries.

  • Check the data set names for SYSLIB, SYSIN, SYSLMOD, and SYSLIN in the SAGASM and LINKALL inline procedures.

3. Make ADALNK Available to the ADATCP-Enabled Adabas Nucleus

The (re)linked ADALNK must be made available to the ADATCP-enabled Adabas nucleus.

On BS2000 systems do one of the following:

  • In a permanent file attached to the link name DDLNKPAR, set parameter ADALNK IDTNAME=iiiiiiii (where iiiiiiii is the IDTNAME where the system in being run); or

  • In the SSFB2C(S) job supplied in the Adabas source library, provide the following setting: B2CONFIG MF=C,ENVNAME=iiiiiiii, where iiiiiiii is the IDTNAME where the system is being run. Then use the sample job ASMBS2(J) to assemble it and use the sample job ALNKUES(J) to prepare the LNKUES.

4. Verify Correct Libraries are Concatenated and Zaps are Applied

Make sure the following libraries are used:

  • Verify that the Adabas 8.2.6 L001 library (or the load library from a later Adabas release) containing the latest ADATCP module is included in the nucleus STEPLIB concatenation.

  • Verify that the latest Entire Net-Work (WCP) and Entire Net-Work TCP/IP Option (WTC) 6.3 SP2 load libraries (or those of later versions) are in the STEPLIB concatenation.

  • In Adabas 8.2 SP5 environments, verify that special Adabas ADASVC zap AY825032 or AI825031 have been applied to the SVC on which the ADATCP-enabled database will run. In Adabas 8.2 SP6 environments, verify that special ADASVC zap AI826007 has been applied to the SVC on which the ADATCP-enabled database will run.

Trouble Shooting

The following table lists some common errors and their causes:

If you get this error: It means that:
ABEND U658 You forgot to link "LNKUES"
AP1001I TRANSPORT ENDPOINT ERROR Someone else is using the same port number
response 254 or
response 5632 (which is really response 22 but byte-swapped)
ADALNK is not configured correctly
ADACM00I:RECV error number 00015 socket 00006 or
ADACM001:RECV error number 01121 socket 00006
A 'connection reset' took place. The client ended abnormally or failed to call the Adabas signoff() method. ADATCP is informing you that the client left; ADATCP will clean up the connection.

Activating the ADATCP Direct TCP/IP Link

Start of instruction setTo activate a direct TCP/IP link to the Adabas nucleus:

  1. Set the ADARUN parameter TCPIP=YES.

  2. Specify a universal resource locator (URL), as described in this section.

Specifying a URL

The URL is a 20-byte address that conforms to the RFC specification for URLs. Use the ADARUN parameter TCPURL to specify the URL required to activate the direct TCP/IP link. For more information, read TCPURL Parameter: TCP/IP Universal Resource Locator.

Managing URLs

The URLs can be managed using the TCPIP operator command, as illustrated below:

TCPIP={ OPEN=url | CLOSE=url | CLOSE }

where url is the URL for the TCP/IP link you want to open or close and has the same format as the ADARUN TCPURL parameter:

api-name:[//]stackid:port-number[:logging-setting[:allowipv6-setting]]

The command allows you to open or close a TCP/IP link to the Adabas nucleus or to close all links. It can only be used when ADARUN TCPIP=YES and all conditions for that setting have been met. This command can be used to close the URL set in the ADARUN TCPURL parameter, or to open or close additional TCP/IP links.

Examples

TCPIP=OPEN=OES://:1234
TCPIP=CLOSE=OES://:1234

To close all open URLs:

TCPIP=CLOSE