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

518 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>Get Control Function Definition (CDRGCTL, QTQGCTL) 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 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>Get Control Function Definition (CDRGCTL, QTQGCTL) API</h2>
<div class="box" style="width: 65%;">
<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="35%">CCSID1</td>
<td align="left" valign="top" width="25%">Input</td>
<td align="left" valign="top" width="30%">Int(4)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">SEL</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Int(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">N1</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Int(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">N2</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Int(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">CTLFDF</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Array of Int(4)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">FB</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Feedback</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Get Control Function Definition (CDRGCTL, QTQGCTL) API gets a requested control
function definition associated with a given CCSID. The following control
function definitions are defined in the CCSID resource repository model:</p>
<ul>
<li>Substitute</li>
<li>New Line</li>
<li>Line Feed</li>
<li>Carriage Return</li>
<li>End of File</li>
</ul>
<p>Additionally, the following
other definitions are included in this repository:</p>
<ul>
<li>Space</li>
<li>String Type</li>
</ul>
<p>Each control function definition is defined as a triplet consisting of:</p>
<ul>
<li>The code point value allocated to the requested control function
definition</li>
<li>Its width in number of bytes</li>
<li>The state number in which the code point is to be used</li>
</ul>
<p>Each control function may be defined for each of the possible code extension
switching states associated with the CCSID. There is, at most, one code point
definition for a control function within a switching state.</p>
<p>If the string type definition
is selected it's value will be returned in the first value of the triplet. The
remaining two values of the triplet will be returned as 0.</p>
<p>A selection parameter (SEL) is used to identify which control function
definition is to be returned by the function.</p>
<!-- 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>Required Parameter Group</h3>
<dl>
<dt><strong>CCSID1</strong></dt>
<dd>INPUT; INT(4)
<p>This variable contains the CCSID value referenced; a positive number in the
range 1 to 65,279.</p>
</dd>
<dt><strong>SEL</strong></dt>
<dd>INPUT; INT(4)
<p>This variable contains the selection specification, a non-negative number in
the range 0 to 255. If the selected control function element is available in
the resource definition for CCSID1, the triplets are returned in the area
starting at CTLFDF. The following values are currently defined for SEL:</p>
<table cellpadding="3">
<!-- cols="10 90" -->
<tr>
<th align="left" valign="top">SEL</th>
<th align="left" valign="top">Selected Control Function</th>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td valign="top">Space</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td valign="top">Substitute</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td valign="top">New Line</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td valign="top">Line Feed</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td valign="top">Carriage Return</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td valign="top">End of File</td>
</tr>
<tr>
<td align="left" valign="top"><em>100</em></td>
<td valign="top">String Type</td>
</tr>
</table>
<br>
</dd>
<dt><strong>N1</strong></dt>
<dd>INPUT; INT(4)
<p>This variable contains the size of the allocated area starting at CTLFDF to
contain the returned data. N1 is specified as a number of elements. Each
triplet is counted as 3 elements. It is a positive number whose minimum value
is 3.</p>
</dd>
<dt><strong>N2</strong></dt>
<dd>I/O; INT(4)
<p>This variable contains the number of values returned in CTLFDF. The first
invocation of this function must have N2 initialized to zero. It is a
non-negative integer and is a multiple of 3 (corresponding to each triplet in
CTLFDF). If no definition is found in the CCSID resource for the requested
element, a value of 0 is returned in N2.</p>
</dd>
<dt><strong>CTLFDF</strong></dt>
<dd>OUTPUT; INT(4)
<p>The start of the area to contain the selected definition elements. Each
element is a triplet of 3 binary(4) values. For each triplet, the first value
is the code point, the second is the code point width, and the third value
contains the switching state number. There is one triplet returned for each
switching state for CCSID1. An undefined element is indicated by a zero state
number in the corresponding CTLFDF entry.</p>
<p>If the string type definition
is selected it's value will be returned in the first value of the triplet. The
remaining two values of the triplet will be returned as 0. The following table
provides a definition of each of the string types:</p>
<table border width="80%">
<tr>
<th valign="top">String Type</th>
<th valign="top">Text Type</th>
<th valign="top">Numeric Shaping</th>
<th valign="top">Orientation</th>
<th valign="top">Text Shaping</th>
<th valign="top">Symmetrical Swapping</th>
</tr>
<tr>
<td align="center" valign="top" width="15%">4</td>
<td align="left" valign="top" width="10%">Visual</td>
<td align="left" valign="top" width="20%">Passthrough</td>
<td align="left" valign="top" width="15%">LTR</td>
<td align="left" valign="top" width="20%">Shaped</td>
<td align="center" valign="top" width="20%">Off</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Implicit</td>
<td align="left" valign="top">Arabic</td>
<td align="left" valign="top">LTR</td>
<td align="left" valign="top">Unshaped</td>
<td align="center" valign="top">On</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Implicit</td>
<td align="left" valign="top">Arabic</td>
<td align="left" valign="top">RTL</td>
<td align="left" valign="top">Unshaped</td>
<td align="center" valign="top">On</td>
</tr>
<tr>
<td align="center" valign="top">7(*)</td>
<td align="left" valign="top">Visual</td>
<td align="left" valign="top">Passthrough</td>
<td align="left" valign="top">Contextual *</td>
<td align="left" valign="top">Unshaped-Ligatures</td>
<td align="center" valign="top">Off</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Visual</td>
<td align="left" valign="top">Passthrough</td>
<td align="left" valign="top">RTL</td>
<td align="left" valign="top">Shaped</td>
<td align="center" valign="top">Off</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Visual</td>
<td align="left" valign="top">Passthrough</td>
<td align="left" valign="top">RTL</td>
<td align="left" valign="top">Shaped</td>
<td align="center" valign="top">On</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="left" valign="top">Implicit</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">Contextual LTR</td>
<td align="left" valign="top">&nbsp;</td>
<td align="center" valign="top">On</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="left" valign="top">Implicit</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">Contextual RTL</td>
<td align="left" valign="top">&nbsp;</td>
<td align="center" valign="top">On</td>
</tr>
</table>
<p>(*) Field orientation is left to right (LTR), when first alphabetic
character is a Latin one, and right to left (RTL) when it is a Bidi (RTL)
character; characters are unshaped, but LamAlef ligatures are kept, and not
broken into constituents.</p>
</dd>
<dt><strong>FB</strong></dt>
<dd>OUTPUT; Feedback
<p>The function returns in this feedback array the processing status (and any
associated reason) for this function. The field type is an array of three
32-bit two's complement binary values (12 bytes, or 96 bits); the status code
is a non-negative number in the first 16 bits, and the reason code is a
non-negative number in the second 16 bits. The following are specific meanings
of the status code and associated reason code values (in hexadecimal) contained
in the first 32 bits of FB.</p>
</dd>
</dl>
<br>
<h3>Feedback Codes and Conditions</h3>
<table border width="80%">
<tr>
<th align="center" valign="top">Status</th>
<th align="center" valign="top">Reason</th>
<th align="left" valign="top">Meaning</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0000</td>
<td align="center" valign="top" width="10%">0000</td>
<td align="left" valign="top" width="80%">The function completed
successfully.</td>
</tr>
<tr>
<td align="center" valign="top">0001</td>
<td align="center" valign="top">0001</td>
<td align="left" valign="top">CCSID1 value is not in the CCSID resource
repository.</td>
</tr>
<tr>
<td align="center" valign="top">0001</td>
<td align="center" valign="top">0004</td>
<td align="left" valign="top">One or more of the requested control function
definitions are undefined (as indicated by a zero value for its corresponding
state number in CTLFDF).</td>
</tr>
<tr>
<td align="center" valign="top">0001</td>
<td align="center" valign="top">000A</td>
<td align="left" valign="top">The requested control function definition element
in the CCSID resource for CCSID1 was not found.</td>
</tr>
<tr>
<td align="center" valign="top">0002</td>
<td align="center" valign="top">0001</td>
<td align="left" valign="top">CCSID1 value is 0, which is reserved for
indicating a default in a hierarchy. The caller must resolve the default
before calling this function.</td>
</tr>
<tr>
<td align="center" valign="top">0003</td>
<td align="center" valign="top">0001</td>
<td align="left" valign="top">CCSID1 has one of the special-purpose CCSID
values in the range 65,280 to 65,535.</td>
</tr>
<tr>
<td align="center" valign="top">0004</td>
<td align="center" valign="top">0001</td>
<td align="left" valign="top">The allocated length (value of N1) for the area
to contain returned values was insufficient to contain all the output data that
is to be returned.</td>
</tr>
<tr>
<td align="center" valign="top">0005</td>
<td align="center" valign="top">0002</td>
<td align="left" valign="top">N2 is greater than N1. However, the start of the
next block of data to be returned is outside the valid range 1 to N2max.</td>
</tr>
<tr>
<td align="center" valign="top">0005</td>
<td align="center" valign="top">0003</td>
<td align="left" valign="top">The value specified in the SEL parameter is not
supported.</td>
</tr>
<tr>
<td align="center" valign="top">0005</td>
<td align="center" valign="top">000A</td>
<td align="left" valign="top">N2 is less than or equal to N1, but is not
0.</td>
</tr>
<tr>
<td align="center" valign="top">0006</td>
<td align="center" valign="top">0001</td>
<td align="left" valign="top">The CCSID resource repository was not found.</td>
</tr>
<tr>
<td align="center" valign="top">0006</td>
<td align="center" valign="top">0002</td>
<td align="left" valign="top">The CCSID resource repository is currently
unavailable.</td>
</tr>
<tr>
<td align="center" valign="top">0007</td>
<td align="center" valign="top">0001</td>
<td align="left" valign="top">The system CCSID resource repository accessed by
the function was found to be not valid in the structure.</td>
</tr>
<tr>
<td align="center" valign="top">0008</td>
<td align="center" valign="top">0001</td>
<td align="left" valign="top">CCSID1 value is not in the range 0 to
65,535.</td>
</tr>
<tr>
<td align="center" valign="top">0008</td>
<td align="center" valign="top">0002</td>
<td align="left" valign="top">N1 is greater than the maximum permitted in this
implementation. (The maximum permitted is 99.)</td>
</tr>
<tr>
<td align="center" valign="top">0008</td>
<td align="center" valign="top">000A</td>
<td align="left" valign="top">N1 is less than 3.</td>
</tr>
<tr>
<td align="center" valign="top">0008</td>
<td align="center" valign="top">000B</td>
<td align="left" valign="top">SEL value is not in the range 0 to 255.</td>
</tr>
</table>
<p>Exceptions issued: CPF9872 - Program &amp;1 in library &amp;2 ended.</p>
<br>
<h3>Usage Notes</h3>
<ol>
<li>The maximum number of code extension states (and the associated
corresponding code pages) for the CCSID depends on the ES. Most CCSIDs have
only one state. The maximum is four for the CCSIDs registered to date, though
some future CCSIDs may have more. A calling function can set N1 to 48, to
accommodate up to 16 triplets of information without overflow.<br>
<br>
</li>
<li>The code point value for any control function definition can be in the
range X'00000000' to X'7FFFFFFF' -- only up to 4-byte code points can be
defined. The code point width values can be 1 to 4 (bytes).
<p>For example, for CCSID 00037, the return value, if the space was asked for,
would be X'00000040'. This is interpreted as a 1 byte value of X'40'.</p>
</li>
</ol>
<hr>
API introduced: V3R6
<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>