dbxlate

Description

Translate a character string from one character set to another.

Syntax

int dbxlate(dbproc, src, srclen, dest, destlen, xlt,
          srcbytes_used, srcend, status)
 
 DBPROCESS     dbproc;
 char                    *src;
 int                       srclen;
 char                    *dest;
 int                       destlen;
 DBXLATE           *xlt;
 int                       *srcbytes_used;
 DBBOOL            srcend;
 int                    *status;

Parameters

dbproc: A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and the server.

src: A pointer to the string to be translated.

srclen: The length, in bytes, of src. If srclen is -1, src is assumed to be null-terminated.

dest: A pointer to the buffer to contain the translated string, including a null terminator.

destlen: The size, in bytes, of the buffer to contain the translated string. If destlen is -1, dest is assumed to be large enough to hold the translated string and its null terminator.

xlt: A pointer to a translation structure used to translate character strings from one character set to another. The translation structure is allocated using dbload_xlate.

srcbytes_used: The number of bytes actually translated. If the fully translated string would overflow dest, dbxlate translates only as much of src as will fit. If destlen is -1, srcbytes_used is srclen.

srcend: A boolean value indicating whether or not more data is arriving. If srcend is "true," no more data is arriving. If srcend is "false," src is part of a larger string of data to be translated, and it is not the end of the string.

status

A pointer to a code indicating the status of the translated character string. The following table lists the possible values for status:

**Table 2-30: Values for status**
Value of status	To indicate
DBXLATE_XOF	The translated string overflowed dest.
DBXLATE_XOK	The translation succeeded.
DBXLATE_XPAT	The last bytes of src are the beginning of a pattern for which there is a translation. These bytes were not translated.

Returns

The number of bytes actually placed in dest on success; a negative integer on error.

Usage

dbxlate translates a character string from one character set to another. It is useful when the server character set differs from the display device’s character set.

The following code fragment illustrates the use of dbxlate:

char        destbuf[128];

 int         srcbytes_used;

 DBXLATE     *xlt_todisp;

 DBXLATE     *xlt_tosrv;

dbload_xlate((DBPROCESS *)NULL, "iso_1",

      "trans.xlt", &xlt_tosrv, &xlt_todisp);

 printf("Original string: \n\t%s\n\n",

      TEST_STRING);

 dbxlate((DBPROCESS *)NULL, TEST_STRING,

      strlen(TEST_STRING), destbuf, -1, xlt_todisp,

      &srcbytes_used);

 printf("Translated to display character set: \

      \n\t%s\n\n", destbuf);

 dbfree_xlate((DBPROCESS *)NULL, xlt_tosrv,

      xlt_todisp);