| Previous | Contents | Index |
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.
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. |
The TPware client stub module calls the code conversion functions to perform the following conversions of Kanji text data:
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:
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 |
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 |
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:
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 |
The code conversion module consists of the following three functions:
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:
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.
#include "stdl_cnv_code.h"int stdl_code_conv_init(fnp_p *fn_ptr)
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.
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.
#include "stdl_cnv_code.h"int stdl_convert_wchar_to_wire(wchar_t *inbuf, size_t inlen, char *outbuf)
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.
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.
#include "stdl_cnv_code.h"int stdl_convert_wire_to_wchar(char *inbuf, size_t inlen, wchar_t *outbuf)
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.
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 |