Enabling Universal Encoding Support (UES) for Your Adabas Nucleus

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 called universal encoding support (UES). Entire Net-Work detects when it is connected to a target database that converts data and passes the data through to Adabas without converting it.

UES is enabled by default for the link routine ADALNK.

Note:
The use of UES-enabled link routines is transparent to applications, including applications that do not require UES translation support: it is not necessary to disable UES support.

Load Module and Translation Tables

No source module for ADALNK is delivered with this version of Adabas. The module ADALNK already has the UES component, LNKUES, and the translation tables ASC2EBC and EBC2ASC bound to it.

The ADALNK module consists of ADALNK, ADAL2P and LNKUES. You can bind modified ASC2EBC or EBC2ASC translation tables to ADALNK-BASE using the job ALNKUES.

The two standard translation tables are:

  • ASC2EBC: ASCII to EBCDIC translation; and

  • EBC2ASC: EBCDIC to ASCII translation.

It should only be necessary to modify these translation tables in the rare case when a country-specific character other than A-Z a-z 0-9 must be used in the Additions 1 (user ID) or Additions 3 field of the control block.

The Adabas translation table pair is provided in the section Translation Tables.

Job Steps

Job library member ALNKUES is an example job of how to link ADALNK with the UES components.

JCL Required for UES and TCP/IP Support

For information on the JCL required for UES and TCP/IP support, read JCL Required for UES and TCP/IP Support (BS2000).

Calling LNKUES

LNKUES is called only on ADALNK requests (X‘08’), (X‘0C’) with reply (X‘10’) or (X‘1C‘) and reply (X‘20’) calls if the first byte of the communication ID contains X‘01’ and the second byte does not have the EBCDIC (X‘04’) bit set.

For requests, LNKUES receives control before UEXITB. For replies, LNKUES receives control after UEXITA.

Required Environment

The Adabas database must be UES-enabled. See Adabas DBA Tasks and the ADACMP and ADADEF utilities in Adabas Utilities for more information.

Connection Possibilities

UES-enabled databases are connected to machines with different architectures through Software AG's internal product software (APS) or through Entire Net-Work (WCP).

Adabas SQL Gateway (ACE) clients may not be strictly EBCDIC in an environment where databases are connected through Software AG’s internal product software (APS).

JCL Required for UES Support

The nucleus job statements for a UES nucleus require the following items:

  • BLSLIB access to the APS module libraries is required, so these extras statements are required: 

    /SET-FILE-LINK APSLIB,$SAG.APSvrs.LIB
/SET-FILE-LINK BLSLIBnn,$SAG.APSvrs.LIB

    Note:
    Newer APS module libraries are updates of the original. We advise you to copy the original, merge the new library into it, and reference the merged library in the JCL.

  • The job needs to contain the procedure call below to access the DDECSOJ object library: 

    /CALL-PROCEDURE ($SAG.APSvrs.LIB,LMSLINKLIB),(LNK-NAME=BLSLIBn1)

    ---where BLSLIBn1 is last in the BLSLIB sequence

  • The DDECSOJ SET-FILE-LINK statement should point to the ECS encoding objects $SAG.ADAvrs.ECnn library.

  • No special Software AG internal product software (APS) parameters need to be set.

    The setting of extra options on the START-PROGRAM statement can be done as follows: 

    /START-PROGRAM ($SAG.ADAvrs.MOD,ADARUN),-
/ RUN-MODE=*ADVANCED(ALT-LIB=YES,LOAD-INF=*REF,UNRES=*DELAY,-
/ MESSAGE=*ERROR)

  • An example of Adabas session job control for UES (BS2000) is supplied in the $SAG.ADAvrs.SRC(ADANUCU,J) library element.

Note:
The Software AG internal product software (APS) batch system will create a subtask job with the same user attributes as the UES nucleus job. This job will be stopped automatically when the UES nucleus is stopped.

Linking LNKUES to ADALNK for Data Conversion

Adabas is delivered with the module LNKUES for Universal Encoding Support (UES). LNKUES converts data in the Adabas buffers and byte-swaps, if necessary, depending on the data architecture of the caller. LNKUES is fix bound to ADALNK.

LNKUES is called only on ADALNK request (X’1C’) and reply (X’20’) calls if the first byte of the communication ID contains X’01’ and the second byte does not have the EBCDIC (X’04’) bit set.

  • For requests, LNKUES receives control before UEXITB

  • For replies, LNKUES receives control after UEXITA

By default, two translation tables are linked into LNKUES/ADALNK:

  • ASC2EBC: ASCII to EBCDIC translation; and

  • EBC2ASC: EBCDIC to ASCII translation

Note:
It should only be necessary to modify these translation tables in the rare case that some country-specific character other than "A-Z a-z 0-9" must be used in the Additions 1 (user ID) or Additions 3 field of the control block.

If you prefer to use the same translation tables that are used in Entire Net-Work:

  • in ASC2EBC and EBC2ASC, change the COPY statements from UES2ASC and UES2EBC to NW2ASC and NW2EBC, respectively.

  • reassemble the translation tables and relink LNKUES/ADALNK.

Both the Adabas and Entire Net-Work translation table pairs are provided in section Translation Tables. You may want to modify the translation tables or create your own translation table pair. Be sure to (re)assemble the translation tables and (re)link LNKUES/ADALNK. 

/ASS-SYSDTA *SYSCMD
/STA-PROG $TSOLNK
MODULE ADALNK,LIB=USER.MOD,ELEM=ADALNK
NCAL
LINK SYMBOLS *KEEP
INCLUDE ADALNK,ADABAS.MOD
INCLUDE ASC2EBC,ADABAS.MOD
INCLUDE EBC2ASC,ADABAS.MOD
BIND
/ASS-SYSDTA *PRIM

The (re)linked ADALNK must be made available to Entire Net-Work. 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.