501 lines
16 KiB
HTML
501 lines
16 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">
|
||
|
<!-- 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>
|
||
|
Syntax<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<pre>
|
||
|
#include <iconv.h>
|
||
|
|
||
|
iconv_t <strong>iconv_open (<em>tocode, fromcode</em>)
|
||
|
</strong>
|
||
|
|
||
|
|
||
|
char *tocode;
|
||
|
char *fromcode;
|
||
|
|
||
|
</pre>
|
||
|
|
||
|
<br>
|
||
|
Service Program: QTQICONV<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
Default Public Authority: *USE<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
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 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 &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>
|
||
|
|