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

490 lines
14 KiB
HTML
Raw 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">
<title>iconv()--Code Conversion 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 -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<!--End Header Records -->
<body>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>iconv()--Code Conversion API</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<!-- iddvc RMBR -->
<br>
<pre>
#include &lt;iconv.h&gt;
size_t <strong>iconv (<em>cd, inbuf, inbytesleft,
outbuf, outbytesleft</em>)
</strong>
iconv_t cd;
char **inbuf;
size_t *inbytesleft;
char **outbuf;
size_t *outbytesleft;
</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()</strong> function converts a buffer of characters
specified by the <em>inbuf</em> parameter from one coded character set
identifier (CCSID) into another CCSID and stores the converted characters into
a buffer specified by the <em>outbuf</em> parameter. (The <em>inbuf</em>
parameter points to a variable that points to the first character in the input
buffer. The <em>outbuf</em> parameter points to a variable that points to the
first available byte in the output buffer.) The CCSIDs used are those in the
conversion descriptor, cd, which was returned from the call to either the
<strong>iconv_open()</strong> or the <strong>QtqIconvOpen()</strong>
function.</p>
<p>On input, the <em>inbytesleft</em> parameter indicates the number of bytes
in <em>inbuf</em> to be converted. Similarly, the <em>outbytesleft</em>
parameter indicates the number of bytes available in <em>outbuf</em>. These
values are decremented when the conversion is done, such that on return they
indicate the state of their associated buffers. For encodings dependent on
shift state, <strong>iconv()</strong> changes the shift state of the conversion
descriptor to match the shift state at the end of the input buffer. For
subsequent calls to <strong>iconv()</strong>, conversion begins using the
current shift state of the conversion descriptor. The only state-dependent
encodings in which <strong>iconv()</strong> supports the updating of the
conversion descriptor shift state is mixed-byte EBCDIC.</p>
<p>For encodings dependent on shift state, the conversion descriptor can be
returned to its initial shift state by calling <strong>iconv()</strong> with
<em>inbuf</em> equal to a null pointer, or with <em>inbuf</em> pointing to a
null pointer. The conversion descriptor can also be set to always return to its
initial shift state by specifying the appropriate shift state alternative on
the <strong>iconv_open()</strong> and <strong>QtqIconvOpen()</strong> APIs.
When <strong>iconv()</strong> is called with the conversion descriptor set in
this way, <strong>iconv()</strong> begins conversion from the initial shift
state.</p>
<p>If the input buffer ends with an incomplete character or shift sequence,
conversion stops after the previous successfully converted bytes. If the output
buffer is not large enough to hold the entire converted input, conversion stops
just prior to the input bytes that would cause the output buffer to
overflow.</p>
<p>During conversion, <strong>iconv()</strong> may encounter valid characters
in the input buffer that do not exist in the target CCSID. This is known as a
character mismatch. In this case, <strong>iconv()</strong> performs the
conversion based on the conversion alternative specified on the <strong>
iconv_open()</strong> function.</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>cd</strong></dt>
<dd>INPUT
<p>The conversion descriptor returned by the <strong>iconv_open()</strong> or
<strong>QtqIconvOpen()</strong> function that represents the following:</p>
<ul>
<li>CCSIDs to convert from and to<br>
<br>
</li>
<li>The conversion alternative to use for character mismatches<br>
<br>
</li>
<li>The substitution alternative<br>
<br>
</li>
<li>The shift-state alternative<br>
<br>
</li>
<li>The input length option<br>
<br>
</li>
<li>The error option for mixed data<br>
<br>
</li>
</ul>
</dd>
<dt><strong>inbuf</strong></dt>
<dd>I/O
<p>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 conversion. The maximum size of the
input buffer is 16 773 104 bytes.</p>
</dd>
<dt><strong>inbytesleft</strong></dt>
<dd>I/O
<p>A pointer to a variable containing the number of bytes to the end of the
input buffer to be converted. This variable is decremented to reflect the
number of bytes still not converted in the input buffer. The maximum number of
bytes that can be converted is 16 773 104.</p>
</dd>
<dt><strong>outbuf</strong></dt>
<dd>OUTPUT
<p>A pointer to a variable (pointer) that points to the first available byte in
the output buffer. This variable (pointer) is updated to point to the byte
following the last byte of converted output data. The maximum size of the
output buffer is 16 773 104.</p>
</dd>
<dt><strong>outbytesleft</strong></dt>
<dd>I/O
<p>A pointer to a variable containing the number of the available 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
available is 16 773 104.</p>
</dd>
</dl>
<br>
<h3>Restrictions</h3>
<p>If an error occurs during one of the following requested conversions, the
<em>inbuf</em>, <em>inbytesleft</em>, <em>outbuf</em>, and <em>
outbytesleft</em> parameters may not be updated properly. (ES means encoding
scheme.)</p>
<ul>
<li>EBCDIC mixed-byte (ES X'1301') to or from ASCII mixed-byte (ES X'2300')<br>
<br>
</li>
<li>EBCDIC mixed-byte (ES X'1301') to or from ASCII double-byte (ES
X'2200')<br>
<br>
</li>
<li>EBCDIC double-byte (ES X'1200') to or from ASCII mixed-byte (ES
X'2300')<br>
<br>
</li>
<li>EBCDIC double-byte (ES X'1200') to or from ASCII double-byte (ES
X'2200')</li>
</ul>
<p>If the input length option field (on the call to <strong>
iconv_open()</strong> or <strong>QtqIconvOpen()</strong>) is set for a
NULL-terminated input buffer and the conversion completes successfully, the
<em>inbuf</em> parameter is not updated for conversions involving the following
encoding schemes:</p>
<ul>
<li>Encoding scheme X'2300'<br>
<br>
</li>
<li>Encoding scheme X'4100'<br>
<br>
</li>
<li>Encoding scheme X'4403'<br>
<br>
</li>
<li>Encoding scheme X'5100'<br>
<br>
</li>
<li>Encoding scheme X'5200'<br>
<br>
</li>
<li>Encoding scheme X'5404'<br>
<br>
</li>
<li>Encoding scheme X'5405'<br>
<br>
</li>
<li>Encoding scheme X'5700'<br>
<br>
</li>
</ul>
<p>If the input length option field (on the call to <strong>
iconv_open()</strong> or <strong>QtqIconvOpen()</strong>) is set for a
NULL-terminated input buffer and an error occurs during the conversion, the
<em>inbytesleft</em> parameter is not updated for conversions involving the
following encoding schemes:</p>
<ul>
<li>Encoding scheme X'2300'<br>
<br>
</li>
<li>Encoding scheme X'4100'<br>
<br>
</li>
<li>Encoding scheme X'4403'<br>
<br>
</li>
<li>Encoding scheme X'5100'<br>
<br>
</li>
<li>Encoding scheme X'5200'<br>
<br>
</li>
<li>Encoding scheme X'5404'<br>
<br>
</li>
<li>Encoding scheme X'5405'<br>
<br>
</li>
<li>Encoding scheme X'5700'</li>
</ul>
<br>
<h3>Return Value</h3>
<p>If the entire input buffer is successfully converted, <strong>
iconv()</strong> may return the number of nonidentical conversions performed
based on the substitution alternative. See <a href="iconvopn.htm">
iconv_open()--Code Conversion Allocation API</a> and <a href="QTQICONV.htm">
QtqIconvOpen()--Code Conversion Allocation API</a>. Otherwise, zero will be
returned.
If an error occurs, <strong>iconv()</strong> returns
-1 in the return value, 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>[E2BIG]</strong></dt>
<dd>Insufficient space.
<p>Conversion stopped due to lack of space in the output buffer or there was
not enough space to store the NULL character in the output buffer.</p>
</dd>
<dt><strong>[EBADDATA]</strong></dt>
<dd>Shift state not valid in input data
<p>The beginning shift state of the input data buffer does not correspond to
the shift state of the conversion descriptor. A shift-state sequence was
encountered that tried to change the shift state of the input buffer to the
current shift state of the conversion descriptor. For example, an EBCDIC
shift-in control character may have been encountered while the conversion
descriptor indicated single-byte state. This error is only supported for EBCDIC
mixed-byte (X'1301') encoding schemes.</p>
</dd>
<dt><strong>[EBADF]</strong></dt>
<dd>Descriptor not valid.
<p>The conversion descriptor (cd) parameter is not valid.</p>
</dd>
<dt><strong>[ECONVERT]</strong></dt>
<dd>The mixed input data contained DBCS characters.
<p>Input conversion stopped due to the occurrence of DBCS characters in the
input data when converting from a mixed-byte encoding scheme. The shift state
for EBCDIC mixed data remains in the initial single-byte shift state. This
error can only be returned when the mixed error option has been set accordingly
for the <strong>QtqIconvOpen()</strong> or <strong>iconv_open()</strong>
function.</p>
<p>This error is supported only for the following conversions:</p>
<ul>
<li>EBCDIC mixed-byte (encoding scheme X'1301') to any single-byte encoding
scheme<br>
<br>
</li>
<li>ASCII mixed-byte (encoding scheme X'2300') to any single-byte encoding
scheme<br>
<br>
</li>
<li>EBCDIC mixed-byte (encoding scheme X'1301') to EBCDIC mixed-byte (encoding
scheme X'1301')<br>
<br>
</li>
</ul>
</dd>
<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 stopped because of an incomplete character or shift state
sequence at the end of the input buffer.</p>
</dd>
<dt><strong>[ENOBUFS]</strong></dt>
<dd>Number of bytes for the input or output buffer not valid, or the input
length cannot be determined.
<p>The specified number of bytes for <em>inbytesleft</em> or <em>
outbytesleft</em> is not valid. If the input length option field (on the call
to <strong>iconv_open()</strong> or <strong>QtqIconvOpen()</strong>) specifies
that <strong>iconv()</strong> determines the length of the input buffer and if
<strong>iconv()</strong> cannot find a NULL character in the input buffer, this
error could be returned.</p>
</dd>
<dt><strong>[ENOMEM]</strong></dt>
<dd>Not enough space
<p>Insufficient storage space was available to perform the conversion.</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="iconvopn.htm">iconv_open()</a>--Code Conversion Allocation API<br>
<br>
</li>
<li><a href="QTQICONV.htm">QtqIconvOpen()</a>--Code Conversion Allocation
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>