357 lines
10 KiB
HTML
357 lines
10 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>QlgTransformUCSData()--Transform UCS Data API</title>
|
||
|
|
<!-- Begin Header Records ========================================= -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- NETMG2 SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
||
|
|
<!-- RCHVMW2 on 29 Jan 1999 at 10:01:37 -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- File Edited December 2001 -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>QlgTransformUCSData()--Transform UCS Data API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <qlgusr.h>
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
int QlgTransformUCSData(int <em>xformtype</em>,
|
||
|
|
char <em>**inbuf</em>,
|
||
|
|
size_t <em>*inbytesleft</em>,
|
||
|
|
char <em>**outbuf</em>,
|
||
|
|
size_t <em>*outbytesleft</em>,
|
||
|
|
size_t <em>*outspacereg</em>);
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
Service Program: QLGUSR<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <strong>QlgTransformUCSData()</strong> function transforms, through a
|
||
|
|
formula as compared to a mapping, data from one form of Unicode to another. A
|
||
|
|
transformation type identification is used to specify the type of
|
||
|
|
transformation.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>xformtype</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) The type of transformation requested for execution (that is,
|
||
|
|
UCS2-UTF8, UTF8-UCS2). The <em>xformtype</em> parameter must be one of the
|
||
|
|
following values:
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">Transform from UCS-2 to UTF-8.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
|
<td valign="top">Transform from UTF-8 to UCS-2.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>Other transformation types are one of the following allowable values from
|
||
|
|
the table of transformation types. The first three decimal digits represent the
|
||
|
|
from encoding and the last three decimal digits represent the to encoding. For
|
||
|
|
instance, 030042 is a transform from UTF-32 LE(Little Endian) (030) to UTF-16
|
||
|
|
BE(Big Endian) without a BOM(Byte Order Mark) (042).</p>
|
||
|
|
|
||
|
|
<p>Allowable decimal values:</p>
|
||
|
|
|
||
|
|
<p>010021, 010022, 010031, 010032, 010041, 010042, 010051, 010052, 010061,
|
||
|
|
010062, 020021, 020022, 020031, 020032, 020041, 020042, 020051, 020052, 020061,
|
||
|
|
020062, 030021, 030022, 030031, 030032, 030041, 030042, 030051, 030052, 030061,
|
||
|
|
030062, 040021, 040022, 040031, 040032, 040041, 040042, 040051, 040052, 040061,
|
||
|
|
040062, 050021, 050022, 050031, 050032, 050041, 050042, 050051, 050052, 050061,
|
||
|
|
050062, 060021, 060022, 060031, 060032, 060041, 060042, 060051, 060052, 060061,
|
||
|
|
060062</p>
|
||
|
|
|
||
|
|
<p>Table of transformation types:</p>
|
||
|
|
|
||
|
|
<table border>
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom">Transformation</th>
|
||
|
|
<th align="center" valign="bottom">From:</th>
|
||
|
|
<th align="center" valign="bottom" nowrap>To: with BOM</th>
|
||
|
|
<th align="center" valign="bottom" nowrap>To: without BOM</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="25%">Autodetect</td>
|
||
|
|
<td align="center" valign="top" width="25%">010</td>
|
||
|
|
<td align="center" valign="top" width="25%"> </td>
|
||
|
|
<td align="center" valign="top" width="25%"> </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">UTF-32 BE</td>
|
||
|
|
<td align="center" valign="top">020</td>
|
||
|
|
<td align="center" valign="top">021</td>
|
||
|
|
<td align="center" valign="top">022</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">UTF-32 LE</td>
|
||
|
|
<td align="center" valign="top">030</td>
|
||
|
|
<td align="center" valign="top">031</td>
|
||
|
|
<td align="center" valign="top">032</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">UTF-16 BE</td>
|
||
|
|
<td align="center" valign="top">040</td>
|
||
|
|
<td align="center" valign="top">041</td>
|
||
|
|
<td align="center" valign="top">042</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">UTF-16 LE</td>
|
||
|
|
<td align="center" valign="top">050</td>
|
||
|
|
<td align="center" valign="top">051</td>
|
||
|
|
<td align="center" valign="top">052</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">UTF-8</td>
|
||
|
|
<td align="center" valign="top">060</td>
|
||
|
|
<td align="center" valign="top">061</td>
|
||
|
|
<td align="center" valign="top">062</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>inbuf</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) A pointer to a variable (pointer) that points to the first
|
||
|
|
character in the input buffer. The variable (pointer) is updated to point to
|
||
|
|
the byte following the last byte successfully used in the transformation. The
|
||
|
|
maximum size of the input buffer is 16773104.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>inbytesleft</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) A pointer to a variable containing the number of bytes to the end
|
||
|
|
of the input buffer to be transformed. This variable is decremented to reflect
|
||
|
|
the number of bytes still not transformed in the input buffer. The maximum
|
||
|
|
number of bytes that can be transformed is 16773104.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>outbuf</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) A pointer to a variable (pointer) that points to the first
|
||
|
|
character in the output buffer. This variable (pointer) is updated to point to
|
||
|
|
the byte following the last byte of transformed output data. The maximum size
|
||
|
|
of the output buffer is 16773104.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>outbytesleft</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) A pointer to a variable containing the number of bytes to the end
|
||
|
|
of the output buffer. This variable is decremented to reflect the number of
|
||
|
|
bytes still available in the output buffer. The maximum number of bytes that
|
||
|
|
can be transformed is 16773104.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>outspacereq</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) A pointer to a variable containing the size of the output buffer
|
||
|
|
required to transform the remaining portion of the input buffer. This value
|
||
|
|
will not be accurate if a sequence error (EILSEQ) occurs, either independently
|
||
|
|
or following an E2BIG error.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<p>None</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top"> QlgTransformUCSData() was
|
||
|
|
successful. The entire 'inbuf' was transformed.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>[E2BIG]</em></dt>
|
||
|
|
|
||
|
|
<dd>There was insufficient space in the output buffer. As much of the input
|
||
|
|
buffer as can be contained in the output buffer is transformed. The buffer
|
||
|
|
pointers and byte counters reflect the point at which a complete character
|
||
|
|
could not be transformed into the output buffer.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EBADFUNC]</em></dt>
|
||
|
|
|
||
|
|
<dd>An invalid transform type request was given on the first parameter, <em>
|
||
|
|
xformtype</em>.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EFAULT]</em></dt>
|
||
|
|
|
||
|
|
<dd>The address used for an argument is not correct. In attempting to use an
|
||
|
|
argument in a call, the system detected an address that is not valid. While
|
||
|
|
attempting to access a parameter passed to this function, the system detected
|
||
|
|
an address that is not valid.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EILSEQ]</em></dt>
|
||
|
|
|
||
|
|
<dd>Data provided on an Unicode input buffer was found with an incorrect
|
||
|
|
encoding as determined by the sequence or ordering of the bytes, or a requested
|
||
|
|
<em>xformtype</em> from type did not match the data of the <em>inbuf</em>. Use
|
||
|
|
<em>inbytesleft</em> to determine where the error occurred in the sequence.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EINVAL]</em></dt>
|
||
|
|
|
||
|
|
<dd>An invalid <em>inbytesleft</em> data length was given. More specifically,
|
||
|
|
an uneven number of bytes were provided when transforming from UCS-2.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ENOMEM]</em></dt>
|
||
|
|
|
||
|
|
<dd>There was not enough memory to perform the transformation.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ENOTSUP]</em></dt>
|
||
|
|
|
||
|
|
<dd>Operation not supported. Automatic detection could not find a BOM. A
|
||
|
|
transformation will not be performed.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Usage Notes:</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>When requesting a BOM tagged output buffer the following BOM values will be
|
||
|
|
generated.<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<table border width="40%">
|
||
|
|
<!-- width="40" -->
|
||
|
|
<!-- cols="20 80" -->
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom">BOMS</th>
|
||
|
|
<th align="center" valign="bottom">Hex values</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">UTF-32 BE (020)</td>
|
||
|
|
<td align="left" valign="top">00 00 FE FF</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">UTF-32 LE (030)</td>
|
||
|
|
<td align="left" valign="top">FF FE 00 00</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">UTF-16 BE (040)</td>
|
||
|
|
<td align="left" valign="top">FE FF</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">UTF-16 LE (050)</td>
|
||
|
|
<td align="left" valign="top">FF FE</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">UTF-8 (060)</td>
|
||
|
|
<td align="left" valign="top">EF BB BF</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>A sample conversion:</p>
|
||
|
|
|
||
|
|
<p>transformation type: 030021</p>
|
||
|
|
|
||
|
|
<p>UTF-32 LE (030) -> UTF-32 BE marked (021)</p>
|
||
|
|
|
||
|
|
<p>x'AB 5F 00 00 7C 8E 00 00' -> x'00 00 FE FF 00 00 5F AB 00 00 8E 7C'</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Auto detection is available when there is a BOM in the beginning of the
|
||
|
|
<em>inbuf</em> that represents a Unicode type.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<p>None.</p>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V4R5
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"nls1.htm">National Language Support APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|