friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qlgtrans.htm

357 lines
10 KiB
HTML
Raw Blame History

<!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>
&nbsp;&nbsp;Syntax<br>
<!-- iddvc RMBR -->
<br>
<pre>
#include &lt;qlgusr.h&gt;
</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>
&nbsp;&nbsp;Service Program: QLGUSR<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;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%">&nbsp;</td>
<td align="center" valign="top" width="25%">&nbsp;</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">&nbsp;&nbsp;&nbsp;&nbsp;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) -&gt; UTF-32 BE marked (021)</p>
<p>x'AB 5F 00 00 7C 8E 00 00' -&gt; 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>
Reference in New Issue View Git Blame Copy Permalink