547 lines
15 KiB
HTML
547 lines
15 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>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>
|
|
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>
|
|
Service Program: QLGCASE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
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 &1 outside of valid range.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3BDE E</td>
|
|
<td valign="top">CCSID &1 not supported by API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3BE5 E</td>
|
|
<td valign="top">Value &1 for case request not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3BE8 E</td>
|
|
<td valign="top">Value &1 for DBCS indicator not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3BE9 E</td>
|
|
<td valign="top">Value &1 for reserved field not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3BEA E</td>
|
|
<td valign="top">User-defined table length &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3BEB E</td>
|
|
<td valign="top">Type of request &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3BEC E</td>
|
|
<td valign="top">Value &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 &1 omitted.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3C36 E</td>
|
|
<td valign="top">Number of parameters, &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 &1 API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9801 E</td>
|
|
<td valign="top">Object &2 in library &3 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9803 E</td>
|
|
<td valign="top">Cannot allocate object &2 in library &3.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9804 E</td>
|
|
<td valign="top">Object &2 in library &3 damaged.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9805 E</td>
|
|
<td valign="top">Object &2 in library &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 &1 cannot be accessed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9810 E</td>
|
|
<td valign="top">Library &1 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9830 E</td>
|
|
<td valign="top">Cannot assign library &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>
|
|
|