# Compaq TP Desktop Connector
Getting Started

Previous | Contents | Index

# Appendix B
Guide to Kanji Text Data Code Conversion

TPware products provide Japanese text support. This appendix provides code conversion information for TPware products running on the Windows NT platform.

These Kanji code conversion functions are supported for C input adapters with DCE or MSRPC output adapters.

# B.1 Introduction to Kanji Text Data Conversion

Kanji text data can be encoded using any one of several methods. An STDL TP application must be able to support the exchange of Kanji data across multiple platforms.

TPware products provide an API for converting Kanji text data. The conversion allows Kanji text data to be passed among different platforms. TPware code conversion functions convert internal data format (wide character) to and from STDL wire data format. However, you can replace the conversion functions that Compaq provides with your own conversion functions.

Note ACMSxp code conversion functions convert internal data format (wide character) to and from STDL wire data format. For information about ACMSxp code conversion, see the ACMSxp Version 3.2 release notes.

## B.1.1 Calling the Code Conversion Functions

The TPware client stub module calls the code conversion functions to perform the following conversions of Kanji text data:

- From internal data format (wide character) to wire data format
- From wire data format to internal data format

When DCE or MSRPC output adapter types are specified in a client stub module, a conversion function is called from the stub prior to and following a remote procedure call (RPC). The client stub module converts Kanji text data from internal data format to wire data format prior to the transmission of the data, and then converts from wire data format to internal data format upon receipt of the data returned as a result of the RPC.

## B.1.2 STDL Wire Data Format

The X/Open Structured Transaction Definition Language (STDL) Specification defines encoding rules for Kanji text data sent on the wire. The specification defines encoding rules for the JIS X 0208-1983 and JIS X 0212-1990 character sets. The specification does not define encoding rules for User Defined Characters (UDCs). Compaq extends the encoding rules to include UDCs. These encoding rules will conform to any future encoding rules that The Open Group defines for UDCs. Unicode supports the JIS X 0208-1990 character set which is an updated version of JIS X 0208-1983.

The code conversion functions use the following encoding rules for wire data format:

- JIS X 0208-1990 character set
  The wire data format for JIS X 0208-1990 characters is encoded in the least seven bits of the octet tuple, with the most significant bit of each octet set to 0. The encoding of the seven bits of the octet tuple is defined using the Graphic Character Code Table (Table 1) of JIS X 0208-1990.
- JIS X 0212-1990 character set
  The STDL wire data format for JIS X 0212-1990 characters is encoded in the least seven bits of the octet tuple, with the most significant bit of each octet set to 1. The encoding of the seven bits of the octet tuple is defined using the Graphic Character Code Table (Table 1) of JIS X 0212-1990.
- UDC (User Defined Character)
  The most significant bit of the first octet of a UDC code is set to 1, and the most significant bit of the second octet is set to 0. Thus, each UDC code is formatted into a "1xxxxxxx 0xxxxxxx" bit representation. The UDCs in the JIS X 0208-1990 and JIS X 0209-1990 areas are treated as part of each character set rather than as UDCs.

# B.2 Using the Code Conversion Functions

The client stub module calls the code conversion functions when wire data format specified by the STDL data type compiler option (`-D` flag) is stdlwire, and a DCE or MSRPC output adapter is specified by the `-a` flag. The calling procedure is embedded in the client stub module by the STDL compiler. When compiling STDL task groups referencing records that contain Kanji text data, use the STDL data type compiler option flag, as shown in the following example:

    -D kanji:wchar:stdlwire

The client stub calls the code conversion functions unless customer-written code conversion functions are specified.

For more information about the STDL data type compiler option (`-D` flag), see the compiler section of this manual.

## B.2.1 Using Customer-Written Conversion Functions

To use customer-written code conversion functions, define the STDL_STDLWIRE_CONV_RTN_FILE environment variable. The value of the environment variable must be a full path specification of the DLL containing the customer-written code conversion functions. For example:

    set STDL_STDLWIRE_CONV_RTN_FILE=C:\bin\code_convert.dll

## B.2.2 Character Code Mapping Tables

Use the code mapping table to map the code of UDCs between Unicode and wire data format. The JIS X 0221-1995 standard defines the mapping rule between JIS X 0208-1990/JIS X 0212-1990 characters and ISO/IEC 10646-1:1993 UCS-2 characters. There is no standard that defines a mapping rule for UDCs because a UDC is a customer-defined character. The code mapping table is a customer-defined table, in which mapping rules for UDCs are defined. The code conversion function loads the code mapping table by default if a customer-defined code mapping table is not specified.

### B.2.2.1 Default Character Code Mapping Table

The code conversion module converts characters using a code mapping table. The default mapping table provided by Compaq handles characters specifically defined in the JIS X 0208-1990 and JIS X 0212-1990 standards, and handles user-defined characters in Unicode (code range 0xE000-0xF8FF). Unicode user-defined characters (code range 0xE000-0xF8FF) are mapped into a subset of the available user-defined characters area of wire data format (code range 0xA121-0xE528).

### B.2.2.2 Using a Customer-Defined Code Mapping Table

To use a customer-defined code mapping table, define the STDL_STDLWIRE_CONV_MAP_FILE environment variable. The value of the environment variable must be a full file specification of the DLL containing the customer-defined code mapping table. For example:

    set STDL_STDLWIRE_CONV_MAP_FILE=C:\bin\code_convert_map.dll

### B.2.2.3 Creating a Code Mapping Table

The STDL_CNV_GENMAP command creates a code mapping table file from a mapping data source file.

The format of the STDL_CNV_GENMAP command is as follows:

`STDL_CNV_GENMAP mapping_data_source_file`

The command creates a file named STDL_CNV_STDLWIRE_MAP.DLL in the current directory.

The mapping data source file contains the mapping between Unicode and Super DEC Kanji character codes. Specify mapping data in the format shown below:

`Unicode_character_code:Super_DEC_Kanji_character_code`

The syntax rules for the mapping data source file's records are listed below:

- Specify both the Unicode character code and the Super DEC Kanji character code in hexadecimal form. Do not add the prefix 0x to the hexadecimal value.
- The Unicode character code must be in the first column.
- Use a colon (:) to separate the Unicode character code and the Super DEC Kanji character code.
- The Super DEC Kanji character code must be the last data on a line.
- The record cannot contain any spaces.
- Place an exclamation point (!) in the first column to begin a comment line.

The following shows an example of valid lines in a mapping data source file:

    ! This is a comment line.!

    E000:A121
    E001:A122
    E002:A123
    E003:A124
    E004:A125

# B.3 Creating a Customer-Written Code Conversion Module

The code conversion module consists of the following three functions:

- Initialization function
  - Returns entry points for the two conversion functions.
  - The name must be stdl_code_conv_init.
- Internal-to-wire conversion function
  - Converts Kanji text data from internal data format to wire data format.
  - You decide the function's name.
- Wire-to-internal conversion function
  - Converts Kanji text data from wire data format to internal data format.
  - You decide the function's name.

## B.3.1 Code Conversion Development and Execution Setup

The code conversion functions must be linked as a DLL to be explicitly loaded by the client stub module.

To develop a code conversion DLL, perform the following steps:

1. Develop the customer-written code conversion functions.
2. Compile the code conversion functions.
3. Link the functions as a DLL.

The initialization function stdl_code_conv_init() must be exported at link time. Specify the function name exactly as shown in the following example:

    /export:stdl_code_conv_init

The DLL is explicitly loaded by the client stub module.

To set up for execution, define the environment variable STDL_STDLWIRE_CONV_RTN_FILE described in Section B.2.1.

# B.4 Character Code Conversion Functions

The following pages describe the three functions used in the character code conversion module.

Example B-1 provides a conversion module template.

# B.5 Initialization Function

Initializes the code conversion functions. This function must set the entry points for the two functions that perform the conversions: the function that converts internal data format to wire data format and the function that converts wire data format to internal data format.

Prior to communication with systems on different platforms, the code conversion initialization function is called once by the client stub.

## Format

> #include "stdl_cnv_code.h"

> int stdl_code_conv_init(fnp_p *fn_ptr)

## Arguments

> ### fn_ptr

> Type: fnp_p *
> Access: read
> Mechanism: by reference
> The data structure for the function pointer defined in the stdl_cnv_code.h header file.

> The function pointers are:

> fn_stdl_wchar_to_wire | The function to convert from internal data format to wire data format.
> fn_stdl_wire_to_wchar | The function to convert from wire data format to internal data format.

## Return Status

> Status | Description
> --- | ---
> CNV_S_SUCCESS | Successful completion
> CNV_S_FAILURE | Failure

# B.6 Conversion Function: Internal Data Format to Wire Data Format

Converts characters in the input buffer from internal data format (wide character) to wire data format. The resulting characters are stored in the output buffer.

If the input buffer contains an invalid character, the conversion stops after the last successful conversion and the function returns an error status.

Note that you supply the real name of the function; the name stdl_convert_wchar_to_wire is used here for simplicity's sake.

## Format

> #include "stdl_cnv_code.h"

> int stdl_convert_wchar_to_wire(wchar_t *inbuf, size_t inlen, char *outbuf)

## Arguments

> ### inbuf

> Type: wchar_t *
> Access: read
> Mechanism: by reference
> The input buffer containing Kanji text in internal data format. The internal data is in wide character format and is not NULL terminated.

> ### inlen

> Type: size_t
> Access: read
> Mechanism: by reference
> The maximum number of Kanji characters to be converted.

> ### outbuf

> Type: char *
> Access: write
> Mechanism: by value
> The output buffer for wire data. The output buffer is allocated by the client stub module. The buffer size is large enough to store data converted to wire data format. The client stub allocates 16 bits of buffer area for each wire data character.

## Return Status

> Status | Description
> --- | ---
> CNV_S_SUCCESS | Successful completion
> CNV_S_FAILURE | Failure

# B.7 Conversion Function: Wire Data Format to Internal Data Format

Converts characters in the input buffer from wire data format to internal data format (wide character). The resulting characters are stored in the output buffer.

If the input buffer contains an invalid character, the conversion stops after the last successful conversion and the function returns an error status.

Note that you supply the real name of the function; the name stdl_convert_wire_to_wchar is used here for simplicity's sake.

## Format

> #include "stdl_cnv_code.h"

> int stdl_convert_wire_to_wchar(char *inbuf, size_t inlen, wchar_t *outbuf)

## Arguments

> ### inbuf

> Type: char *
> Access: read
> Mechanism: by reference
> The input buffer containing Kanji text in wire data format. Wire data uses 16 bits for each character and is not NULL terminated.

> ### inlen

> Type: size_t
> Access: read
> Mechanism: by reference
> The maximum number of wire data format characters to be converted.

> ### outbuf

> Type: wchar_t *
> Access: write
> Mechanism: by value
> The output buffer for internal format data. Internal data is in wide character format. The output buffer is allocated by the client stub module. The buffer size is the same number of characters specified for the Kanji text data field.

## Return Status

> Status | Description
> --- | ---
> CNV_S_SUCCESS | Successful completion
> CNV_S_FAILURE | Failure

# B.8 Conversion Module Template

The following example provides a conversion module template.

Example B-1 Conversion Module Template

    /*
    ***************************************************************************
    *
    * Code conversion module template
    *
    ***************************************************************************
    */
    #include "stdl_cnv_code.h"

    /*
    * Function Prototype
    */
    static int stdl_wchar_to_wire(wchar_t *, size_t, char *);
    static int stdl_wire_to_wchar(char *, size_t, wchar_t *);

    /*
    **************************************************************************
    * Description:
    * This initialization function returns entry points for conversion
    * functions.
    *
    * Arguments:
    * fnp_p *fn_ptr output Entry point.
    *
    * Return value:
    * If initialization is completed successfully, return CNV_S_SUCCESS.
    * Otherwise, return CNV_S_FAILURE as error status.
    *
    * Note:
    * This function name, stdl_code_conv_init, must be exported.
    *
    **************************************************************************
    */
    __declspec(dllexport) int stdl_code_conv_init(fnp_p *fn_ptr)
    {
    /* This initialization is required */
    fn_ptr->fn_stdl_wchar_to_wire = stdl_wchar_to_wire;
    fn_ptr->fn_stdl_wire_to_wchar = stdl_wire_to_wchar;

    /* Customer-Written Initialization Logic */

    /*
    * if (ERROR)
    * return CNV_S_FAILURE;
    */

    return CNV_S_SUCCESS;
    }

    /*
    **************************************************************************
    * Description:
    * This function converts Kanji text data from wide character to wire
    * format.
    *
    * Arguments:
    * wchar_t *inbuf input Input string.
    * size_t inlen input Number of input characters.
    * char *outbuf output Output string.
    *
    * Return value:
    * If conversion is completed successfully, return CNV_S_SUCCESS.
    * Otherwise, return CNV_S_FAILURE as error status.
    *
    **************************************************************************
    */
    int stdl_wchar_to_wire(
    wchar_t *inbuf,
    size_t inlen,
    char *outbuf)
    {

    /* Customer-Written Conversion Logic */

    /*
    * if (ERROR)
    * return CNV_S_FAILURE;
    */

    return CNV_S_SUCCESS;
    }

    /*
    **************************************************************************
    * Description:
    * This function converts Kanji text data from wire format to wide
    * character.
    *
    * Arguments:
    * char *inbuf input Input string.
    * size_t inlen input Number of input characters.
    * wchar_t *outbuf output Output string.
    *
    * Return value:
    * If conversion is completed successfully, return CNV_S_SUCCESS.
    * Otherwise, return CNV_S_FAILURE as error status.
    *
    **************************************************************************
    */
    int stdl_wire_to_wchar(
    char *inbuf,
    size_t inlen,
    wchar_t *outbuf)
    {

    /* Customer-Written Conversion Logic */

    /*
    * if (ERROR)
    * return CNV_S_FAILURE;
    */

    return CNV_S_SUCCESS;
    }

    /*
    **************************************************************************
    *
    * End of code conversion module template
    *
    **************************************************************************
    */

Index | Contents