ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/iconvopn.htm

501 lines
16 KiB
HTML
Raw Permalink Normal View History

2024-04-02 14:02:31 +00:00
<!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">
<!-- 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 -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
<title>iconv_open()--Code Conversion Allocation API</title>
</head>
<body>
<!--End Header Records -->
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>iconv_open()--Code Conversion Allocation API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Syntax<br>
<!-- iddvc RMBR -->
<br>
<pre>
#include &lt;iconv.h&gt;
iconv_t <strong>iconv_open (<em>tocode, fromcode</em>)
</strong>
char *tocode;
char *fromcode;
</pre>
<br>
&nbsp;&nbsp;Service Program: QTQICONV<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#USAGE_NOTES">Usage
Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>iconv_open()</strong> function performs the necessary
initializations to convert character encodings from the source CCSID identified
by the <em>fromcode</em> parameter to the CCSID identified by the <em>
tocode</em> parameter. 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>
QtqIconvOpen()</strong> API except that the input types of <em>fromcode</em>
and <em>tocode</em> are character strings.</p>
<p>The conversion descriptor remains valid in a job until that job closes it
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&nbsp;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 a string containing the CCSID to convert to. Refer to <a href=
"#HDRFROMTO">Format of fromcode and tocode</a> for the layout of this
string.</p>
</dd>
<dt><strong>fromcode</strong></dt>
<dd>INPUT
<p>A pointer to the string containing the CCSID to convert from, the type of
conversion to perform, the substitution alternative, the shift-state
alternative, the input length option, and the mixed error option. Refer to <a
href="#HDRFROMTO">Format of fromcode and tocode</a> for the layout of this
string.</p>
</dd>
</dl>
<br>
<h3>Format of fromcode and tocode</h3>
<p>The <em>fromcode</em> string 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%">CHAR(8)</td>
<td align="left" valign="top" width="60%">The word IBMCCSID</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%">CHAR(5)</td>
<td align="left" valign="top" width="60%">Character representation of CCSID
number</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">13</td>
<td align="center" valign="top" width="10%">D</td>
<td align="left" valign="top" width="20%">CHAR(3)</td>
<td align="left" valign="top" width="60%">Conversion 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%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Substitution alternative</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">17</td>
<td align="center" valign="top" width="10%">11</td>
<td align="left" valign="top" width="20%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Shift-state alternative</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">18</td>
<td align="center" valign="top" width="10%">12</td>
<td align="left" valign="top" width="20%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Input length option</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">19</td>
<td align="center" valign="top" width="10%">13</td>
<td align="left" valign="top" width="20%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Error option for mixed data</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%">CHAR(12)</td>
<td align="left" valign="top" width="60%">Reserved</td>
</tr>
</table>
<p>The <em>tocode</em> string 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%">CHAR(8)</td>
<td align="left" valign="top" width="60%">The word IBMCCSID</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%">CHAR(5)</td>
<td align="left" valign="top" width="60%">Character representation of CCSID
number</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">13</td>
<td align="center" valign="top" width="10%">D</td>
<td align="left" valign="top" width="20%">CHAR(19)</td>
<td align="left" valign="top" width="60%">Reserved</td>
</tr>
</table>
<br>
<br>
<h3>Field Descriptions</h3>
<p><strong>Character representation of CCSID number.</strong> A character
representation of the CCSID number to convert from or to. Valid CCSID values
are in the range 00001 through 65533. The following special value is supported
on the <em>fromcode</em> and <em>tocode</em> parameters:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>00000</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. The following values can be used:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>000</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>057</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
set (DBCS) characters.</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 to the end of
the input buffer being converted; 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 being 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.
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>.
<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. 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 (057) for the
conversion alternative field. Performance is decreased when using this
alternative.</p>
</td>
</tr>
</table>
<p><strong>The word IBMCCSID.</strong> The 8-byte character field that contains
the characters I, B, M, C, C, S, I, D. The characters must be in uppercase.</p>
<br>
<h3>Return Value</h3>
<p>If successful, <strong>iconv_open()</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>iconv_open()</strong> returns -1 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 &amp;1 API.</td>
</tr>
</table>
<br>
<br>
<h3><a name="USAGE_NOTES">Usage Notes</a></h3>
<p>This API is threadsafe if threads that share a conversion descriptor do not
attempt to preserve the shift state.</p>
<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>
<br>
<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>