On-line data conversion

In some circumstances, data conversion between ASCII and EBCDIC is required. This happens when XCICS Transaction Server, running on a UNIX/Linux or Windows system (ASCII), communicates and exchanges data with a mainframe system (EBCDIC) .

XCICS provides a transparent conversion system for particular features such:

User may request XCICS, at configuration time, to a perform ASCII-EBCDIC translation for a specific resource when invoked/accessed on a server region running on a mainframe.

To do that, user have to:

The dynamic conversion system may be specified and invoked on resource such:

Whenever a dynamic conversion is required, the name of the converter routine must be specified in the resource definition.

Temporary storage queues, which have no definition, are the only exception: user can define one only converter routine for TS queue, and specify it the general settings of XCICS: in this case the routine must be smart enough to recognize by itself (using the information provided by XCICS) the data being converted.

In the following example, a system named CICA is defined and the os=EBCDIC is specified, the program REMOTPGM is specifying CICA as server region name and a converter function.

With this definition, every time the program REMOTPGM is linked to, XCICS activates the DFHMIR transaction on the remote region, and performs a DPL. Before to send the commarea to the server region and before to return to the program the commarea returned by the server program,  XCICS will invoke the "remotca" routine from the "libcaconv.so" library to convert the data from ASCII to and from EBCDIC.

I.e.

define connection sysid=CICA,
    type=sna, mode=LU62APPB, netname=CICSIBM0,
    os=ebcdic, acquire;
define program name=REMOTPGM,
language=cobol,
sysid=CICA,
converter_function=remotca, converter_lib=libcaconv.so;

Conversion routines

Routines invoke by the XCICS online data conversion system must be contained in a shared library file, and must conform to the this prototype:

int XCICS_EXIT_PROGRAM function_name(struct xcics_conversion_info *p);

The function name is choosed by the user according to its standards/preferences. In order to avoid interferences with other routines, its strongly suggested to choose a "unique" identifier to prefix the user-written functions.

The parameter supplied to the function is a pointer to a data structured according to the definitions supplied in "cicsconv.h".

If the routine returns 0 (zero) to the caller XCICS uses the data converted by the routine. Any other value is treated as an error, so data is handles AS-IS and no conversion occurs.

By means of "cicsconv.h" header file some macros are available to make coding easier.

Information supplied to the routines

By means of the C structure xcics_conversion_info the following information are provided to the converter function:

Automatic routine generation

Conversion routines may be automatically generated using the XCONV xmlconverter utility, by means of the -area option. In the following example, the structure of the COMMAREA of REMOTPGM, described in the COBOL copybook REMOTCA.cpy is automatically translated into an online conversion routine.

First of all, the copybook is analyzed and its structure is converted into an XML description of the structure itself:

# cpy2xml -o REMOTCA.xml REMOTCA.cpy

Then, the XML is transalted into a C conversion routine, suitable for the online system:

# xmlconverter -area -o remotca.c REMOTCA.xml

and, at the end, the routine is compiled and linked into a shared library or DLL.

Multiple record structures

When a COMMAREA or a record structure contains multiple definitions (redefines), dynamic conversion system can still be used, but the programmer must alos code the recognization logic.

So the programmer have to:

I.e.

#include "cics_exit.h"
#include "cicsconv.h"
 
int XCICS_EXIT_PROGRAMS convert_multi_ca(struct xcics_conversion_info *p) {
       unsigned char *code0001;
       BYTE function_code[4];
       register int i;    
 
       /**
        * depending on the conversion direction
        * the record code is translated
        */
       memcpy(function_code, p->area, 4);
 
       if (p->direction==CONVERT_EBCDIC_TO_ASCII) {
               CICSCONV_E2A_CHAR(function_code, 4);
       }
 
       /** if record type 1 call the converter func 1 */
       if (memcmp(function_code, "0001", 4)==0) {
               return rectype01(p);
       }
       /** if record type 2 call the converter func 2 */
       if (memcmp(function_code, "0002", 4)==0) {
               return rectype02(p);
       }
 
       /** this area is not recognized */
       return -1;     
}     

Conversion macros

The "cicsconv.h" includes a number of conversion macros which may be used to translate the data. These macros translate data according to the codepage and DBCS table configured in the region.

Compile and Link

To compile and link your conversion routines please follow the rules and the instructions for your system.