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

547 lines
15 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>Convert Case (QLGCNVCS, QlgConvertCase) 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 -->
<!-- This file has undergone html cleanup July 2002 by JET -->
<!--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>Convert Case (QLGCNVCS, QlgConvertCase) API</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Request control block</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Input data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Output data</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Length of data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Service Program: QLGCASE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Convert Case (OPM, QLGCNVCS; ILE, QlgConvertCase) API provides a case
conversion function that can be directly called by any application program.
This API can be used to convert character data to either uppercase or
lowercase.</p>
<p>This API supports conversion for single-byte, mixed-byte, and UCS2
(Universal Multiple-Octet Coded Character Set with 16 bits per character)
character sets. For the mixed-byte character set data, only the single-byte
portion of the data is converted. This API does not convert double-byte
character data from any double-byte character set (DBCS) or from a mixed-byte
character set.</p>
<p>This API can base case conversion on a CCSID, whereas the Convert Data
(QDCXLATE) API uses only table objects.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Table Authority</em></dt>
<dd>*USE<br>
<br>
</dd>
<dt><em>Table Library</em></dt>
<dd>*USE<br>
<br>
</dd>
<dt><em>Table Lock</em></dt>
<dd>*SHRNUP</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Request control block</strong></dt>
<dd>INPUT; CHAR(*)
<p>The information that defines the case conversion alternatives. Refer to <a
href="#HDRFORMRCB">Format of Request Control Block</a> for details.</p>
</dd>
<dt><strong>Input data</strong></dt>
<dd>INPUT; CHAR(*)
<p>The input data being converted.</p>
</dd>
<dt><strong>Output data</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The converted output data that is returned to the calling program. The
storage allocated for this output buffer parameter must be at least as long as
the input data buffer or unpredictable results may occur.</p>
</dd>
<dt><strong>Length of data</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the data being converted in the input data parameter. Any data
that extends beyond the specified length is ignored. The specified length must
be a value greater than 0 and less than 16 773 104 bytes.</p>
<p>The length of the storage allocated for the output data is assumed to be the
same size as the length of the input data.</p>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3><a name="HDRFORMRCB">Format of Request Control Block</a></h3>
<p>The following table shows the layout of the request control block. For a
detailed description of each field, see <a href="#HDRRCBFD">Field
Descriptions</a>.</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 valign="bottom" align="center">Dec</th>
<th valign="bottom" align="center">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%">Type of request</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> The rest of
the layout when the request is 1 (CCSID format)</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%">CCSID of input data</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%">Case request</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%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Reserved</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> The rest of
the layout when the request is 2 (table object format)</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%">DBCS indicator</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(20)</td>
<td align="left" valign="top" width="60%">Qualified table name</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> The rest of
the layout when the request is 3 (user-defined format)</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%">DBCS indicator</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%">Reserved</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%">Length of user-defined table</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(*)</td>
<td align="left" valign="top" width="60%">User-defined case conversion
table</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRCBFD">Field Descriptions</a></h3>
<p><strong>Case request.</strong> A request that specifies the type of case
conversion to be performed. Valid values are:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td valign="top">Convert the input data to uppercase.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td valign="top">Convert the input data to lowercase.</td>
</tr>
</table>
<p><strong>CCSID of input data.</strong> The coded character set identifier
(CCSID) of the input data to be converted. Case conversion is performed based
on this CCSID. For a list of valid CCSIDs, see the <a href=
"../nls/rbagsglobalmain.htm">Globalization</a> topic in the iSeries Information
Center. The valid values are:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td valign="top">The CCSID of the job is used to determine the CCSID of the
data to be converted. If the job CCSID is 65535, the CCSID from the default
CCSID (DFTCCSID) job attribute is used.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1-65533</em></td>
<td valign="top">A valid CCSID in this range.</td>
</tr>
</table>
<p><strong>DBCS indicator.</strong> The indicator that specifies whether or not
double-byte data exists in the input data.</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td valign="top">Input data does not contain any double-byte values.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td valign="top">Input data may contain mixed values where the double-byte data
is surrounded by shift-out and shift-in characters. Any double-byte data found
between a shift-out and shift-in character is ignored and returned to the
output data buffer as is.</td>
</tr>
</table>
<p>When the DBCS indicator is 0 but the input data contains double-byte values,
this API processes the double-byte data as single-byte data. This also pertains
to the shift-in and shift-out characters. It is recommended that an indicator
of 0 be used when processing input data that contains only single-byte data
because the performance is faster.</p>
<p><strong>Length of user-defined table.</strong> The length (in bytes) of the
user-defined case conversion table. This length must be 256.</p>
<p><strong>Qualified table name.</strong> The table used to convert the data.
The first 10 characters contain the table name. The second 10 characters
contain the name of the library in which the table resides.</p>
<p>The system-supplied tables only provide uppercasing of the data. For a list
of valid case conversion tables supplied by the system, see the <a href=
"../nls/rbagsglobalmain.htm">Globalization</a> topic in the iSeries Information
Center.</p>
<p>You can use the following special values for the library name:</p>
<table cellpadding="3">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td valign="top">The library list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td valign="top">The job's current library.</td>
</tr>
</table>
<p><strong>Reserved.</strong> A reserved field that must be set to hexadecimal
zeros.</p>
<p><strong>Type of request.</strong> The input information format of the case
conversion being requested. The layout of the request control block parameter
is based on one of the following values:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td valign="top">CCSID format</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td valign="top">Table object format</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td valign="top">User-defined format</td>
</tr>
</table>
<p><strong>User-defined case conversion table.</strong> The user-defined case
conversion table used to convert the input data.</p>
<br>
<h3>Error Messages</h3>
<table width="100%">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td valign="top" width="15%" >CPF24B4 E</td>
<td valign="top" width="85%" >Severe error while addressing parameter list.</td>
</tr>
<tr>
<td valign="top">CPF3BC7 E</td>
<td valign="top">CCSID &amp;1 outside of valid range.</td>
</tr>
<tr>
<td valign="top">CPF3BDE E</td>
<td valign="top">CCSID &amp;1 not supported by API.</td>
</tr>
<tr>
<td valign="top">CPF3BE5 E</td>
<td valign="top">Value &amp;1 for case request not valid.</td>
</tr>
<tr>
<td valign="top">CPF3BE8 E</td>
<td valign="top">Value &amp;1 for DBCS indicator not valid.</td>
</tr>
<tr>
<td valign="top">CPF3BE9 E</td>
<td valign="top">Value &amp;1 for reserved field not valid.</td>
</tr>
<tr>
<td valign="top">CPF3BEA E</td>
<td valign="top">User-defined table length &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3BEB E</td>
<td valign="top">Type of request &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3BEC E</td>
<td valign="top">Value &amp;1 for reserved field not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C12 E</td>
<td valign="top">Length of data is not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C1E E</td>
<td valign="top">Required parameter &amp;1 omitted.</td>
</tr>
<tr>
<td valign="top">CPF3C36 E</td>
<td valign="top">Number of parameters, &amp;1, entered for this API was not
valid. (This message applies only to the QLGCNVCS API, not the QlgConvertCase
API.)</td>
</tr>
<tr>
<td valign="top">CPF3C90 E</td>
<td valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td valign="top">CPF3CF1 E</td>
<td valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CF2 E</td>
<td valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td valign="top">CPF9801 E</td>
<td valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td valign="top">CPF9803 E</td>
<td valign="top">Cannot allocate object &amp;2 in library &amp;3.</td>
</tr>
<tr>
<td valign="top">CPF9804 E</td>
<td valign="top">Object &amp;2 in library &amp;3 damaged.</td>
</tr>
<tr>
<td valign="top">CPF9805 E</td>
<td valign="top">Object &amp;2 in library &amp;3 destroyed.</td>
</tr>
<tr>
<td valign="top">CPF9807 E</td>
<td valign="top">One or more libraries in library list deleted.</td>
</tr>
<tr>
<td valign="top">CPF9808 E</td>
<td valign="top">Cannot allocate one or more libraries on library list.</td>
</tr>
<tr>
<td valign="top">CPF9809 E</td>
<td valign="top">Library &amp;1 cannot be accessed.</td>
</tr>
<tr>
<td valign="top">CPF9810 E</td>
<td valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td valign="top">CPF9830 E</td>
<td valign="top">Cannot assign library &amp;1.</td>
</tr>
</table>
<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>