444 lines
14 KiB
HTML
444 lines
14 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>QtqIconvOpen()--Code Conversion Allocation 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. -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!-- NETMG2 SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
|
<!-- RCHVMW2 on 29 Jan 1999 at 10:01:37 -->
|
|
<!--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>QtqIconvOpen()--Code Conversion Allocation API</h2>
|
|
|
|
<div class="box" style="width: 60%;"><br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<pre>
|
|
iconv_t <strong>QtqIconvOpen (<em>tocode, fromcode</em>)
|
|
</strong>
|
|
|
|
|
|
QtqCode_T *tocode;
|
|
QtqCode_T *fromcode;
|
|
|
|
</pre>
|
|
|
|
<br>
|
|
Service Program: QTQICONV<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The <strong>QtqIconvOpen()</strong> function performs the necessary
|
|
initializations to convert character encodings from the source CCSID identified
|
|
by the <em>fromcode</em> to the CCSID identified by the <em>tocode</em>. It
|
|
then returns a conversion descriptor of data type <samp>iconv_t</samp>. For
|
|
EBCDIC mixed-byte encodings, the conversion descriptor is set to the initial
|
|
single-byte shift state.</p>
|
|
|
|
<p><strong>Note:</strong> This API performs the same function as the <strong>
|
|
iconv_open()</strong> API except that the input type of <em>fromcode</em> and
|
|
<em>tocode</em> is of data type <samp>QtqCode_T</samp>.</p>
|
|
|
|
<p>The conversion descriptor remains valid in a job until that job closes with
|
|
<strong>iconv_close()</strong> or the job ends. Keeping unneeded conversion
|
|
descriptors active results in storage being allocated for these. To reduce this
|
|
storage, you should call the <strong>iconv_close()</strong> API if you no
|
|
longer need this conversion descriptor. The number of active descriptors is
|
|
limited to a maximum of 104 000 active descriptors per process. This
|
|
number may be reduced if the job has many active threads.</p>
|
|
|
|
<br>
|
|
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
|
|
<!-- Instead, use the commented out coding below to indicate NONE. -->
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<!-- Use this if there are no authorities and locks. -->
|
|
<p>None.</p>
|
|
|
|
<br>
|
|
<h3>Parameters</h3>
|
|
|
|
<dl>
|
|
<dt><strong>tocode</strong></dt>
|
|
|
|
<dd>INPUT
|
|
|
|
<p>A pointer to the structure containing the CCSID to convert to. For the
|
|
layout of this structure, see <a href="#HDRQTQCODE">Format of
|
|
QtqCode_T</a>.</p>
|
|
</dd>
|
|
|
|
<dt><strong>fromcode</strong></dt>
|
|
|
|
<dd>INPUT
|
|
|
|
<p>A pointer to the structure containing the CCSID to convert from, the type of
|
|
conversion to perform, the substitution alternative, and the shift-state
|
|
alternative. For the layout of this structure, see <a href="#HDRQTQCODE">Format
|
|
of QtqCode_T</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3><a name="HDRQTQCODE">Format of QtqCode_T</a></h3>
|
|
|
|
<p>The <strong>QtqCode_T</strong> structure consists of the following.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="center" valign="bottom">Dec</th>
|
|
<th align="center" valign="bottom">Hex</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">CCSID</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">4</td>
|
|
<td align="center" valign="top" width="10%">4</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Conversion alternative</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">8</td>
|
|
<td align="center" valign="top" width="10%">8</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Substitution alternative</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">12</td>
|
|
<td align="center" valign="top" width="10%">C</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Shift-state alternative</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">16</td>
|
|
<td align="center" valign="top" width="10%">10</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Input length option</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">20</td>
|
|
<td align="center" valign="top" width="10%">14</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Error option for mixed data</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">24</td>
|
|
<td align="center" valign="top" width="10%">18</td>
|
|
<td align="left" valign="top" width="20%">CHAR(8)</td>
|
|
<td align="left" valign="top" width="60%">Reserved</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<h3>Field Descriptions</h3>
|
|
|
|
<p><strong>CCSID.</strong> The CCSID to convert from or to. Valid CCSID values
|
|
are in the range 1 through 65533. The following special value is supported on
|
|
the <em>fromcode</em> and <em>tocode</em> parameters:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td valign="top">The conversion descriptor is created with the CCSID of the
|
|
current job such that calls to <strong>iconv()</strong> with the conversion
|
|
descriptor use the CCSID of the job at the time the conversion descriptor was
|
|
opened by <strong>iconv_open()</strong>. If the CCSID of the current job is
|
|
65535 (indicating no conversion), the default CCSID from the DFTCCSID job
|
|
attribute is used.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Conversion alternative.</strong> The conversion alternative that is
|
|
selected to convert graphic character data. This value is only used on the <em>
|
|
fromcode</em> parameter; it is ignored on the <em>tocode</em> parameter. The
|
|
following values can be used:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="10 90" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td valign="top">The IBM-defined default conversion method and the associated
|
|
conversion tables. Most of the default tables follow the round-trip conversion
|
|
criterion. For the default tables that do not follow the round-trip conversion
|
|
criterion, see the <a href="../nls/rbagsglobalmain.htm">Globalization</a> topic
|
|
in the iSeries Information center.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>57</em></td>
|
|
<td valign="top">The enforced subset match (substitution) criterion. For the
|
|
CCSID conversion pairs that support this criterion, refer to the <a href=
|
|
"../nls/rbagsglobalmain.htm">Globalization</a> topic in the iSeries Information
|
|
center.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>102</em></td>
|
|
<td valign="top">The best-fit conversion criterion for character mismatch.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Error option for mixed data.</strong> Whether <strong>
|
|
iconv()</strong> returns an error when it converts a character string from a
|
|
mixed-byte encoding scheme and the input buffer contains double-byte character
|
|
(DBCS) characters.</p>
|
|
|
|
<p><strong>Note:</strong> This is only valid on the fromcode parameter and only
|
|
used if the target CCSID is SBCS.</p>
|
|
|
|
<p>Valid values are:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td valign="top">An error is not returned when converting from a mixed-byte
|
|
encoding scheme and the input buffer contains DBCS characters. Instead,
|
|
<strong>iconv()</strong> converts the DBCS characters to the CDRA-standardized
|
|
control character substitute of the target CCSID.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td valign="top">An ECONVERT error is returned in <strong>errno</strong> when
|
|
<strong>iconv()</strong> encounters a DBCS character in the input buffer when
|
|
converting from a mixed-byte encoding scheme.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Input length option.</strong> Whether <strong>iconv()</strong>
|
|
determines the number of bytes to the end of the input buffer being converted.
|
|
This value is only used on the <em>fromcode</em> parameter. The possible values
|
|
follow:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td valign="top">The conversion descriptor is created such that the <strong>
|
|
iconv()</strong> function does not determine the number of bytes; therefore, a
|
|
valid value for the <em>inbytesleft</em> parameter must be specified.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td valign="top">The conversion descriptor is created such that the <strong>
|
|
iconv()</strong> function determines the number of bytes to the end of the
|
|
input buffer to be converted; therefore, the input buffer must end with a NULL
|
|
character. The resulting converted output buffer is ended with a NULL character
|
|
by <strong>iconv()</strong>. The <em>inbytesleft</em> parameter must point to a
|
|
value of zero.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Reserved.</strong> A reserved field that must be set to hexadecimal
|
|
zeros.</p>
|
|
|
|
<p><strong>Shift-state alternative.</strong> Whether the shift state should be
|
|
restored to its initial shift state before conversion is performed by <strong>
|
|
iconv()</strong>. This value is only used on the <em>fromcode</em> parameter;
|
|
it is ignored on the <em>tocode</em> parameter. The following values can be
|
|
used:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td valign="top">The conversion descriptor is not returned to its initial shift
|
|
state.
|
|
|
|
<p><strong>Note:</strong> The conversion descriptor can still be returned to
|
|
its initial shift state by making a separate call to <strong>iconv()</strong>.
|
|
The <em>inbuf</em> must be equal to a null pointer or pointing to a null
|
|
pointer.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td valign="top">The conversion descriptor is always returned to its initial
|
|
shift state.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Substitution alternative.</strong> Whether the number of
|
|
substitution characters encountered in the converted output data is returned by
|
|
<strong>iconv()</strong>. This value is only used on the <em>fromcode</em>
|
|
parameter; it is ignored on the <em>tocode</em> parameter. The following values
|
|
can be used:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td valign="top">The number of substitution characters encountered is not
|
|
returned.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td valign="top">The number of substitution characters encountered is returned.
|
|
This number may be equal to or greater than the actual number of nonidentical
|
|
conversions (substitutions) performed. The substitution character for a
|
|
particular encoding scheme is defined in the Character Data Representation
|
|
Architecture (CDRA).
|
|
|
|
<p><strong>Note:</strong> This value for the substitution alternative is valid
|
|
only when using the enforced subset conversion criterion for the conversion
|
|
alternative. Performance is decreased when using this alternative.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<h3>Return Value</h3>
|
|
|
|
<p>If successful, <strong>QtqIconvOpen()</strong> returns a conversion
|
|
descriptor of data type <samp>iconv_t</samp>. This conversion descriptor must
|
|
be passed unchanged as an input parameter to the <strong>iconv()</strong> and
|
|
<strong>iconv_close()</strong> functions.</p>
|
|
|
|
<p>If unsuccessful, <strong>QtqIconvOpen()</strong> returns -1 and in the
|
|
return value of the conversion descriptor and sets <strong>errno</strong> to
|
|
indicate the error.</p>
|
|
|
|
<br>
|
|
<h3>Error Conditions</h3>
|
|
|
|
<p>The following errors can be returned in <strong>errno</strong>:</p>
|
|
|
|
<dl>
|
|
<dt><strong>[EFAULT]</strong></dt>
|
|
|
|
<dd>Bad address
|
|
|
|
<p>The system detected an address that was not valid when attempting to use an
|
|
argument from the parameter list. An escape message may also be signaled as a
|
|
result.</p>
|
|
</dd>
|
|
|
|
<dt><strong>[EINVAL]</strong></dt>
|
|
|
|
<dd>Parameter not valid.
|
|
|
|
<p>The conversion specified in the <em>fromcode</em> and <em>tocode</em>
|
|
parameters is not supported.</p>
|
|
|
|
<p>When an errno value of EINVAL is returned, check the <em>fromcode</em> and
|
|
<em>tocode</em> parameters for CCSIDs that are not valid or unsupported
|
|
alternatives and options.</p>
|
|
</dd>
|
|
|
|
<dt><strong>[ENOMEM]</strong></dt>
|
|
|
|
<dd>Not enough space.
|
|
|
|
<p>Insufficient storage space is available.</p>
|
|
</dd>
|
|
|
|
<dt><strong>[EUNKNOWN]</strong></dt>
|
|
|
|
<dd>Undetected error
|
|
|
|
<p>An undetected error occurred. Contact your service organization. An escape
|
|
message may also be signaled as a result.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>The following escape messages can be signaled:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<th align="left" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Escape Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24B4 E</td>
|
|
<td valign="top">Severe error while addressing parameter list.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C90 E</td>
|
|
<td valign="top">Literal value cannot be changed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF2 E</td>
|
|
<td valign="top">Error(s) occurred during running of &1 API.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li><a href="iconv.htm">iconv()</a>--Code Conversion API<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="iconvcls.htm">iconv_close()</a>--Code Conversion Deallocation
|
|
API</li>
|
|
</ul>
|
|
|
|
<hr>
|
|
API introduced: V3R1
|
|
|
|
<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>
|
|
|