The major obstacle in communication between client and server applications on diverse systems is that different computer systems use different formats to represent similar types of data. The mainframe (IBM. BS2000, or Facom) is architecturally an EBCDIC format, Big-Endian machine, while most machines running OpenVMS, UNIX, and Windows operating systems are ASCII format machines that use a combination of Big-Endian and Little-Endian architectures.
Note:
For the lowest addressable byte, Big-Endian architecture uses the
most significant byte; Little-Endian architecture uses the least significant
byte.
These different architectures mean that data must be translated in communications between heterogeneous client/server applications to allow for interoperability. Data translation is required in order for a mainframe (IBM, BS2000, or Facom) client application program to communicate with a UNIX or OpenVMS Adabas server or for a UNIX or OpenVMS client application program to access a mainframe (IBM, BS2000, or Facom) Adabas server.
The data translation that is part of this client/server communication occurs partially within Entire Net-Work and the Adabas server. The client application need not be concerned with data conversion.
Entire Net-Work's translation process is centered around the format and length of each field specified in the search and format buffers that are passed with each Adabas call, along with special translation definition parameters. When a request goes through the network conversion routines, each individual field is translated according to the format and length defined for it in the associated search or format buffer.
Note:
The format of all fields in the record and value buffers must be
fully qualified with length and field type if Entire Net-Work will be performing the
translation; otherwise, response code 229 (ADARSP229) is returned to the client
application.
This document covers the following topics:
In addition to fully qualified field definitions, Entire Net-Work provides enhanced translation capabilities that allow:
proper data translation of superfields and superdescriptors
alternative EBCDIC /ASCII translation tables
user exits that override the normal translation process
special handling of field format "X".
Enhanced translation capabilities apply to communications between a client application running on any non-mainframe Entire Net-Work node (e.g., Windows, UNIX, OpenVMS) and an Adabas database on an Entire Net-Work mainframe node.
A superfield is a field that logically contains multiple fields, each of which can have its own format. For example, superfield "SF" can consist of two fields, "SA" which has the format P9, and "SB" which has the format A50. Similarly, a superdescriptor comprises multiple descriptors.
Entire Net-Work supports the translation of superdescriptors and superfields on a field by field basis. This allows superdescriptors and superfields accessed through Entire Net-Work to be properly translated.
Alternative EBCDIC to ASCII and ASCII to EBCDIC translation tables can be specified with Entire Net-Work, allowing you to accommodate unusual translation requirements. For example, if the ASCII character set in use includes characters different from the standard set, a translation table can be provided to translate EBCDIC characters into the required ASCII characters.
Entire Net-Work allows user-written translation exits to override the normal translation process. The Entire Net-Work administrator can develop a translation exit to perform extended translation, such as conversion to or from double-byte character format. User exit modifications can be applied to any field translated by Entire Net-Work.
Within the Entire Net-Work conversion routines, a field format of "X" in the format or search buffer instructs Entire Net-Work to perform no translation of the field. Entire Net-Work only changes the "X" to an "A" before passing the request to the server.
Translation definition statements are required in order to use Entire Net-Work's enhanced translation capabilities. These definitions can be either:
permanently added to the DDKARTE or operating system-dependent configuration member, like other Entire Net-Work statements or
entered at the console as operator commands.
For each superfield or superdescriptor to be translated, a translation definition statement must be added to define the format and length of each field contained in the superfield.
If an alternative translation table or a translation exit is used, a translation definition statement must be added to identify the name of the translation module. A translation module can be applied to all fields within a given file or database. If the name of a translation table or translation exit is specified in a TRANSLATE DEFINE statement for the database or file, it is applied to all fields in the database or file that are specified in lower-level translation definition statements. The translation definition statement for the individual fields need not include the translation module specification if the module has already been specified for the entire database or the entire file.
There are three types of translation definition statements:
| Statement Type | Used to |
|---|---|
| TRANSlat DEFine | Add | add a translation definition. |
| TRANSlat DELETE | Remove | delete a translation definition. |
| TRANSlat DISplay | LISt | display the currently active translation definitions. |
The TRANSlat DEFine | Add statement is used to add a translation definition, in the following format:
TRANSlat DEFine | ADD ID=(dbid,file), -
FIeld=field,-
TOAscii=etoatbl,-
TOEbcdic=atoetbl,-
EXIT=userexit,-
FOrmat=(F1,L1,...,F20,L20)
For more information about syntax conventions and rules used in this section, read Conventions.
Note:
If a required parameter is missing, the message NET004I: INVALID
VALUE FOR KEYWORD FIELD is displayed. If this occurs, reissue the Add statement
with all the required parameters.
ID=(dbid,file)
Specifies the database ID and file number to which this statement applies. Specifying "0" for a database or file identifier indicates all databases or all files. A zero dbid cannot be specified with a non-zero file identifier.
Field=field
Specifies the two byte Adabas short name for the field. Not specifying this operand indicates that the translation definition applies to all fields within the specified database and file. This operand must be specified if the FORMAT operand is specified. This operand cannot be specified if either the database ID or file number is zero (all databases or all files). If this operand is omitted, the TOAscii, TOEbcdic, or EXIT operand must be specified.
TOAscii=etoatbl
Specifies the name of an optional user supplied EBCDIC to ASCII translation table. The name must be 1 to 8 characters long, and the load module or core image module must be accessible at the time the translation definition is entered.
TOEbcdic=atoetbl
Specifies the name of an optional user supplied ASCII to EBCDIC translation table. The name must be 1 to 8 characters long, and the load module or core image module must be accessible at the time the translation definition is entered.
EXIT=userexit
Specifies the name of a user supplied translation exit. The name must be 1 to 8 characters long, and the load module or core image module must be accessible at the time the translation definition is entered.
FOrmat=(F1,L1,....,F20,L20)
Defines 1 to 20 pairs of formats and lengths. These format and length pairs override the format supplied in the search or format buffer and are used to describe the format conversion performed by Entire Net-Work. The formats must be valid Adabas field formats (A,B,F,G,P,U,X) and the length must be valid for the related format.
The specified formats apply to the subfields contained in the field specified with the Field operand. Format can be specified only if the Field operand is also specified.
If the Format operand is omitted, translation is based on the format supplied in the search or value buffer of the Adabas call being processed.
When a translation definition is entered, it is validated; then an attempt is made to add it to the translation definition table. Before adding it, however, the identifying triplet (dbid, file, field) is used to search the table for an existing entry. Duplicate entries are not permitted.
Identifiers must be specified in one of four combinations. The following combinations are supported:
| DBID | File | Field | Comments |
|---|---|---|---|
| non-zero | non-zero | non-zero | Specific field translation |
| non-zero | non-zero | not specified | Specific exit or tables |
| non-zero | zero | not specified | Specific exit or tables |
| zero | zero | not specified | Specific exit or tables |
The TRANSlat DELETE | REMove statement is used to delete a translation definition, in the following format:
TRANSlat DELETE | REMove ID=(dbid,file), -
FIeld=field
ID=(dbid,file)
Specifies the database and file identifiers that this statement applies to. Both the database and file identifiers are numeric values with a range of 0 to 255. The database and file identifiers, along with the field identifier, are used to locate the active translation definition to be removed.
Field=field
Specifies the two byte Adabas short field name. If the translation definition to be deleted was added without the FIeld operand, the FIeld operand must also be omitted in the TRANSlat DELETE statement.
The TRANSlat DISplay | LISt command is used to display the currently active translation definitions. There are no operands for this command format, as follows:
TRANSlat DISplay | LISt
To create an ASCII to EBCDIC (TOEbcdic=) translation module, perform the following steps:
Create a source assembler member (see NETUA2E for an example) that defines a 256-byte translation table.
For each ASCII character being translated, its hexadecimal value is used to index into the translation table, and the EBCDIC value at that location is used as the substitution value.
Assemble the source member.
Link the object code, specifying linkage editor parameters RENT,REUS to prevent loading multiple copies of the load module during normal execution.
For BS2000/OSD, the library WCPvrs.LIB contains two modules, with source code, for ASCII and EBCDIC code page translation. The module E2ASIE translates code page ISO 646, German reference version in code page ISO 8859-1, Latin 1 (for platforms such as Windows). The module A2ESIE translates a code page ISO 88591-1, Latin 1 in code page ISO 646, German reference version.
To create an EBCDIC to ASCII (TOAscii=) translation table, perform the following steps:
Create a source assembler member (see NETUE2A for an example) that defines a 256-byte translation table.
For each EBCDIC character being translated, its hexadecimal value is used to index into the translation table, and the ASCII value at that location is used as the substitution value.
Assemble the source member.
Link the object code, specifying linkage editor parameters RENT,REUS to prevent loading multiple copies of the load module during normal execution.
In addition to creating explicit translation tables at the DBID, file, and field level, you can also alter the two default translation tables used for all ASCII/EBCDIC translation. For modification instructions, see the source member NETCAS for EBCDIC to ASCII translation; see the source member NETCEB for ASCII to EBCDIC translation.
A translation exit provides more detailed control over Entire Net-Work translation. Entire Net-Work calls the exit before and after translating a field for which the database, file, and field IDs match that of a translation definition that specifies the user exit.
The translation exit should be coded to be as efficient as possible. Software AG strongly discourages using supervisor services that may block the network task. The sample application program NETUTRNX may be used as an example.
When the exit is called, the following registers are passed to the application. The exit must save and restore Registers 0-14.
| Register | Description |
|---|---|
| R1 | Address of parameter list. |
| R13 | Address of 18 word save area. |
| R14 | Return address. |
| R15 | Entry point address. |
The address and length of the field can be obtained from the parameter list passed to the exit. The address of the parameter list is contained in Register 1. The DSECT of this parameter list can be found as the source member TDSPARMS. Refer to this source member for details.
The four user work fields in the parameter list are the only fields that can be altered. If the exit requires more work areas, storage can be allocated to obtain a work area. The work area address can then be stored in one of the user work fields. The user work fields are cleared when Entire Net-Work is initialized and are not subsequently altered by Entire Net-Work.
The contents of the user work fields are shared between all active translation exits; care should be taken if more than one exit is concurrently defined. Altering any other fields within the parameter list may cause unpredictable results.
The translation exit may or may not translate a given field; for a superfield, it may translate only certain subfields. If the exit translates the field, it must not alter any storage areas before or after the field being processed.
Upon leaving the exit, a return code can be set in Register 15 to inform Entire Net-Work of the field's translation status. Setting the return code has no effect on Entire Net-Work's storage areas.
If the field is translated, the return code must be set to 4 before leaving the exit. A value of 4 instructs Entire Net-Work to not perform translation. The exit is not called again for the field.
If the field is not translated by the exit, the return code must be set to 0. A value of 0 instructs Entire Net-Work to translate the field.
If only certain subfields within the field are translated, the return code must be set to 8. A value of 8 instructs Entire Net-Work to not process the rest of the field.
The following restrictions apply to the Format and Search Buffers when being processed by the Entire Net-Work conversion routines:
All fields must be specified with length and format. Otherwise, response code 229 (ADARSP229) is returned.
No compressed records. Entire Net-Work translates uncompressed data only.
Text literals are not translated. A text literal (an alphanumeric character string surrounded by quotes) is ignored by the translation process, and its value is not changed.
No field ranges. Fields must be specifically identified.
No undefined MU/PE counts; for example, AA1-N.
The following restrictions are due to different platform implementations:
The maximum length of unpacked numbers is 27 (ASCII), 31 (EBCDIC).
The maximum length of packed numbers is 14 (ASCII), 15 (EBCDIC).
User data provided in a mainframe link routine user exit is not sent to the ASCII-based machine.
ET data (user data that is stored with an ET or CL command) is stored unconverted. When retrieved, it is filled up with blanks in the architecture code of the database if the record buffer length (RBL) is greater than the length of the data actually stored.
ET data stored with command option 1='p' is not supported.
Certain Adabas commands cannot be used in communications between heterogeneous platforms:
Soft coupling is not supported.
Sort sequence for letters, numbers and special characters is different in ASCII (numbers first) and EBCDIC (letters first). This results in different sort sequences, and is relevant for the following Adabas commands:
| Command | Function |
|---|---|
| L3/L6 | Reads a file in logical sequential order based on the sequence of the values for a given descriptor. |
| S2 | Selects a set of records that satisfy given search criteria. |
| S9 | Sorts an ISN list provided by a user or created by a previous Sx Command. |
An L9 command to a mainframe (IBM. BS2000, or Facom) database without a Search Buffer / Value Buffer combination will result in a response code 57 (ADARSP057). Natural for OpenVMS will not deliver the required buffers unless the "starting from" option is specified on the histogram statement.
The C3 command, which is used to store user restart data, is not supported on EBCDIC-based databases.
The following Adabas commands are not supported on ASCII-based databases:
| Command | Explanation |
|---|---|
| A4/E4 | The A4 command updates the contents of one or more fields within a record. The E4 command deletes a record. |
| BT with F option | The BT command backs out all the updates that have been performed during the transaction currently being processed. The F option, which is used to exclude one or more files from the backout process, is not supported on ASCII-based databases. |
| L9 with I or F option | The L9 command returns each value contained in the inverted list for a given descriptor, and the number of records in which the value is contained. The I option returns the ISN for each value in the record buffer; the F option is used to specify the number of the file that contains the descriptor for which values are to be returned. The I option and the F option are not supported on ASCII-based databases. |
| LF with I option | The LF command returns the field definitions for a file. The I option, which causes all field information to be returned in Adabas internal format, is not supported on ASCII-based databases. |
| S5 | The S5 command is used to select the records in one file that are coupled to a given record in another file. |
| Prefetch option | The prefetch option is not supported on ASCII-based databases. However, a new option 'M' has been defined, giving a functionality comparable to the prefetch option. |
When accessing a mainframe (IBM. BS2000, or Facom) database from OpenVMS or UNIX, an application may receive an Adabas response code 17 (ADARSP017 - file not found), even though the file does exist.
This happens because Natural on these platforms issues a restricted OPEN command only, allowing access to files specified in the record buffer on the OPEN command. To resolve the problem, modify the NATPARM module to provide access / update authority to the required files.
The translation process for the different data type fields is described as follows:
| Field Type | Translation Process |
|---|---|
| Alpha | The Entire Net-Work task on the mainframe (IBM. BS2000, or Facom) node has two standard translation tables used by the main Entire Net-Work converter (NETCONV). These two tables handle the pure EBCDIC to ASCII and ASCII to EBCDIC translation. Note that Adabas long alphanumeric fields are not translated. |
| Binary | The translation consists of byte-flipping; that is, the first byte of the binary field is swapped with the last byte; the second byte is swapped with the next to the last byte, and so on, if the partner machine is a byte-swapped architecture. |
| Unpacked | All but the last byte of the field are translated using the described ASCII and EBCDIC translation tables. The last byte, which is the sign, is translated to its appropriate value. |
| Packed | The sign is translated to the appropriate value. |
| Floating | The appropriate type of translation is performed; that is, IEEE, VAX to IBM, IBM to IEEE or VAX. |
Tables translating hexadecimal values to ASCII and EBCDIC values can be found on the internet. Here is one such link: http://www.simotime.com/asc2ebc1.htm.