Version 6.3.1	SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT

In the past, ADABAS had a default internal EBCDIC/ASCII translation table. But in order to provide full flexibility with specific translation tables in complex client/server systems, ADABAS also supports a special code-page user exit.

The ADABAS nucleus calls the user exit when it processes a command that was issued from a remote node. The user exit is called with a pointer to a structure that contains the node name (see the following diagram). The user exit now uses a user-written algorithm to determine which translation table to use, and returns a pointer to a table. Adabas then uses this table for the conversions.

The environment variable ADATRT holds the name of the shared library (UNIX) or dynamic link library (Windows) that is created by the user with the appropriate options. Plain text files with the extension .txt can also be used (see Code Page Support for further information). The default name for the user function is `trt', but any name can be selected, for example:

setenv ADATRT "$ADADIR/db100/adatrt.sl"   (UNIX C shell)
set ADATRT= %ADADIR%\db100\adatrt.dll     (Windows)

or

setenv ADATRT "adatrt.so my_trt"   (UNIX C shell)
set ADATRT=adatrt.dll my_trt            (Windows)

The environment variable ADATRT must be set before the nucleus or a utility is started. If it is not defined, the default internal translation table will be used if an EBCDIC/ASCII conversion is required. If ADATRT is defined, but the library cannot be loaded successfully, the nucleus will abort during its startup phase and a corresponding error message will be issued.

Function Interface

Format: unsigned char *trt (struct trt_entry *)

The trt Structure

trt_node

The basic input is the name of the node that issues the current ADABAS call. On the basis of the node name, the function selects the appropriate code page table. If selected, the function returns a pointer to the table. If nothing is selected, a NULL pointer may be specified to indicate that either no or just the default conversions are to be made.

trt_ctype

The function is called with one of two values. A TRT_INIT call will be performed during the nucleus/utility startup: it will return a value of NULL if it is successful. A TRT_CODE_PAGE call has the node name set so that the function can select a translation table. If the function is called from the utilities ADACMP or ADADCU, the TRT_CODE_PAGE call will be performed once, and the node name will be `adacmp' or `adadcu'.

trt_dbid

This specifies the current database number. This is necessary because the translation table function may be shared between several databases.

Translation Table Layout

Translation tables must be 512 bytes long. The first half is used for translations from the client machine architecture to the server architecture; the second 256 bytes are used for the reverse conversions.

Each table must be a real translation table. This means that the value of the input character is the index to the table, and that the character stored in the corresponding cell will be taken.

The user may use as many translation tables as his heterogeneous environment requires.

Calling Conventions

The following conventions apply to the use of code pages:

• The user-written function is always called if the current Adabas call comes from a remote node and is a read or update command.

• If the user-written function returns a pointer (to a code page), it will be used for the conversion. Only alphanumeric (format A) data will be converted.

• If the user-written function returns a NULL and both the remote and local architectures are the same, no conversion will be performed.

• If the user-written function returns a NULL and the remote and local architectures are different, the default Adabas conversion table will be used for the conversion.

Creating a Code Page User Exit

The Adabas kit contains a corresponding C header file and an example source file for a code page user exit.

UNIX Platforms

The structure trt_entry is defined in the file adauex.h, which is located in $ADADIR/$ADAVERS/inc.

An example source file for the code page user exit (file name adatrt.c) and the corresponding makefile are located in $ADADIR/$ADAVERS/examples/server.

Enter the following in order to build this user exit example:

cd  $ADADIR/$ADAVERS/examples/server

make trt

The shared library for the user exit is created in $ADADIR/$ADAVERS/examples/server.

Windows Platforms

The structure trt_entry is defined in the file adauex.h, which is located in %ADADIR%\%ADAVERS%\inc.

An example source file for the code page user exit (file name adatrt.c) and the corresponding makefile are located in %ADADIR%\%ADAVERS%\..\examples\server.

Enter the following in order to build this user exit example:

cd  %ADADIR%\%ADAVERS%\..\examples\server

nmake trt

The DLL for the user exit created in %ADADIR%\%ADAVERS%\..\examples\server.

Default Translation Tables

The following are the default translation tables used by Adabas.

Conversion ASCII ISO-8-bit (8859-1) to EBCDIC

Note:
Undefined characters not contained in the table will be converted to 0xFF.

Conversion EBCDIC to ASCII ISO-8-bit (8859-1)

Note:
Undefined characters not contained in the table will be converted to 0x7F.

www.softwareag.com

Copyright © 1987-2013 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT