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

785 lines
20 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>Display Help (QUHDSPH) 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. -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--Edited by Kersten Nov 2001 -->
<!-- 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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Display Help (QUHDSPH) API</h2>
<div class="box" style="width: 80%;">
<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%">Help identifier array</td>
<td align="left" valign="top" width="10%">Input</td>
<td align="left" valign="top" width="30%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Number of help identifiers</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Help type</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array(2) of Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Full display title</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(55)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Qualified search index object name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Display type</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Upper-left corner</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array(2) of Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Lower-right corner</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array(2) of Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Cursor location</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array(2) of Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">10</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;Optional Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">11</td>
<td align="left" valign="top" width="50%">Help bookshelf name</td>
<td align="left" valign="top" width="10%">Input</td>
<td align="left" valign="top" width="30%">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="left" valign="top">Border attribute</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array(2) of Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">13</td>
<td align="left" valign="top">Border characters</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array(8) of Char(1)</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 Display Help (QUHDSPH) API displays help information. The help can be
either contextual or extended. It can be formatted as a full display or in a
window.</p>
<p><strong>Contextual help</strong> provides information about a single item,
such as the field on which the user's cursor is positioned when help is
requested. <strong>Extended help</strong> provides help for all the items on
the display; it contains all contextual help items and can contain additional
information as well. A <strong>window</strong> is an area on the display that
is treated as a separate display. Windows have visible boundaries and appear to
overlay the display from which they are requested.</p>
<p>You can use the QUHDSPH API to handle Help key processing in applications
written in data description specifications (DDS) or user-defined data streams
(UDDS). You do not need it to handle help requests in applications that use
record-level DDS display files with DDS help keywords to present panels because
the DDS help keywords handle all help requests.</p>
<p>You do not need to use this API to display help for applications written
using panel groups to present panels, because the UIM handles all help
requests.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Library Authority</em></dt>
<dd>*READ</dd>
<dt><em>Search Index Object Authority</em></dt>
<dd>*USE</dd>
<dt><em>Search Index Object Library Authority</em></dt>
<dd>*READ</dd>
<dt><em>Search Index Object Lock</em></dt>
<dd>*SHRRD</dd>
<dt><em>Panel Group Authority</em></dt>
<dd>*USE</dd>
<dt><em>Panel Group Lock</em></dt>
<dd>*SHRRD</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Help identifier array</strong></dt>
<dd>INPUT; CHAR(*)
<p> An array of the help identifiers to display. The list can contain up to
2000 items. Each item has two parts:</p>
<dl>
<dt><strong>Qualified help panel group name</strong></dt>
<dd>CHAR(20)
<p> The panel group (*PNLGRP) object that contains the help module to display,
and the library in which it is located. (A <strong>panel group</strong> is an
object with an object type of *PNLGRP. It contains display panels, print
panels, or help modules.)</p>
<p> The first 10 characters contain the panel group object name, and the second
10 characters contain the library name. You can use these special values for
the library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table><br>
</dd>
<dt><strong>Help module name</strong></dt>
<dd>CHAR(32)
<p> The name specified on the NAME attribute of a :HELP. tag in the panel group
object. The name must be specified using uppercase, alphabetic characters.</p>
</dd>
</dl>
</dd>
<dt><strong>Number of help identifiers</strong></dt>
<dd>INPUT; BINARY(4)
<p> The number of help identifiers in the help identifier array parameter. The
number must be between 1 and 2000.</p>
</dd>
<dt><strong>Help type</strong></dt>
<dd>INPUT; ARRAY(2) of BINARY(4)
<p> Whether this is a request to display extended or contextual help, and which
help identifiers to display for the latter. For contextual help, only a subset
of the help identifiers in the help identifier array parameter is initially
displayed, and a function key is enabled to display extended help. Extended
help includes all help identifiers in the help identifier array parameter,
including those used in contextual help.</p>
<p> This parameter is a 2-element array of BINARY(4) values. Both elements are
used as indexes into the help identifier array. The array elements are:</p>
<ol>
<li>The first help identifier to display for contextual help. The value must be
greater than or equal to 1, and less than or equal to the number of help
identifiers in the help identifier array.</li>
<li>The last help identifier to display for contextual help. The value must be
greater than or equal to the value specified in the first element of this
parameter, and less than or equal to the number of help identifiers in the help
identifier array.</li>
</ol>
<p> To display extended help, set the value of the first array element to 1 and
the value of the second array element to the value specified in the number of
help identifiers parameter.</p>
</dd>
<dt><strong>Full display title</strong></dt>
<dd>INPUT; CHAR(55)
<p> The default title to use if the help is shown in a full display and if no
title is found in the help panel group object.</p>
</dd>
<dt><strong>Qualified search index object name</strong></dt>
<dd>INPUT; CHAR(20)
<p> The search index (*SCHIDX) object that can be accessed from the help
display, and the library in which it is located. The first 10 characters
contain the search index object name, and the second 10 characters contain the
library name.</p>
<p> You can use the following special value for this parameter:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*NONE</em></td>
<td align="left" valign="top">The search index function is not made available
for this help request. The library name must be blank.</td>
</tr>
</table>
<p> You can use the following special values for the library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<p><strong>Note:</strong> The qualified search index object name must be *NONE
if the help bookshelf name is something other than *NONE.</p>
</dd>
<dt><strong>Display type</strong></dt>
<dd>INPUT; CHAR(1)
<p> Whether the help information is displayed in a full screen or a window. You
must use one of the following values:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>Y</em></td>
<td align="left" valign="top">The help is displayed in a full screen.</td>
</tr>
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">The help can be displayed in a window, depending
on the user option (USROPT) value of the user profile.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Upper-left corner</strong></dt>
<dd>INPUT; ARRAY(2) of BINARY(4)
<p> The upper-left corner of the area on the display for which help is
requested. If the help is displayed in a window, the window is adjacent to the
area identified, if possible. The array elements are:</p>
<ul>
<li>The row number of the upper-left corner</li>
<li>The column number of the upper-left corner</li>
</ul>
<br>
</dd>
<dt><strong>Lower-right corner</strong></dt>
<dd>INPUT; ARRAY(2) of BINARY(4)
<p> The lower-right corner of the area on the display for which help is
requested. If the help is displayed in a window, the window is adjacent to the
area identified, if possible. The array elements are:</p>
<ul>
<li>The row number of the lower-right corner</li>
<li>The column number of the lower-right corner</li>
</ul>
<br>
</dd>
<dt><strong>Cursor location</strong></dt>
<dd>INPUT; ARRAY(2) of BINARY(4)
<p> The position of the cursor when help is requested. If the help is displayed
in a window, this cursor position is used by the UIM to decide the position and
size of the window. The array elements are the row number of the cursor
position and the column number of the cursor position.</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>
<h3>Optional Parameter Group</h3>
<dl>
<dt><strong>Help bookshelf name</strong></dt>
<dd>INPUT; CHAR(8)
<p>This parameter is no longer supported and any value entered will be
ignored.</p>
</dd>
<dt><strong>Border attribute</strong></dt>
<dd>INPUT; ARRAY(2) of CHAR(1)
<p> The border attributes of the pop-up window in which the help may be
displayed. The two array elements are:</p>
<ul>
<li>The border attribute for a monochrome display. The default for a monochrome
display is normal.</li>
<li>The border attribute for a color display. The default for a color display
is blue.</li>
</ul>
<p><strong><a name="Table_1-1">Border attributes</a></strong><br>
</p>
<table border cellpadding="5">
<!-- cols="15 25 70" -->
<tr>
<th align="left" valign="top">Hex Value</th>
<th align="left" valign="top">Color Display</th>
<th align="left" valign="top">Monochrome Display</th>
</tr>
<tr>
<td align="left" valign="top">X'01'</td>
<td align="left" valign="top">Green</td>
<td align="left" valign="top">Normal</td>
</tr>
<tr>
<td align="left" valign="top">X'02'</td>
<td align="left" valign="top">Green<br>
Reverse</td>
<td align="left" valign="top">Reverse Image</td>
</tr>
<tr>
<td align="left" valign="top">X'03'</td>
<td align="left" valign="top">White</td>
<td align="left" valign="top">High Intensity</td>
</tr>
<tr>
<td align="left" valign="top">X'04'</td>
<td align="left" valign="top">Green<br>
Reverse</td>
<td align="left" valign="top">High Intensity Reverse</td>
</tr>
<tr>
<td align="left" valign="top">X'05'</td>
<td align="left" valign="top">Green<br>
Underscore</td>
<td align="left" valign="top">Underscore</td>
</tr>
<tr>
<td align="left" valign="top">X'06'</td>
<td align="left" valign="top">Green Underscore<br>
Reverse</td>
<td align="left" valign="top">Underscore<br>
Reverse</td>
</tr>
<tr>
<td align="left" valign="top">X'07'</td>
<td align="left" valign="top">White<br>
Underscore</td>
<td align="left" valign="top">High Intensity<br>
Underscore</td>
</tr>
<tr>
<td align="left" valign="top">X'08'</td>
<td align="left" valign="top">Nondisplay</td>
<td align="left" valign="top">Nondisplay</td>
</tr>
<tr>
<td align="left" valign="top">X'09'</td>
<td align="left" valign="top">Red</td>
<td align="left" valign="top">Blink</td>
</tr>
<tr>
<td align="left" valign="top">X'0A'</td>
<td align="left" valign="top">Red<br>
Reverse</td>
<td align="left" valign="top">Blink<br>
Reverse</td>
</tr>
<tr>
<td align="left" valign="top">X'0B'</td>
<td align="left" valign="top">Red<br>
Blink</td>
<td align="left" valign="top">Blink<br>
High Intensity</td>
</tr>
<tr>
<td align="left" valign="top">X'0C'</td>
<td align="left" valign="top">Red<br>
Blink<br>
Reverse</td>
<td align="left" valign="top">Blink<br>
High Intensity<br>
Reverse</td>
</tr>
<tr>
<td align="left" valign="top">X'0D'</td>
<td align="left" valign="top">Red<br>
Underscore</td>
<td align="left" valign="top">Blink<br>
Underscore</td>
</tr>
<tr>
<td align="left" valign="top">X'0E'</td>
<td align="left" valign="top">Red<br>
Underscore<br>
Reverse</td>
<td align="left" valign="top">Blink<br>
Underscore<br>
Reverse</td>
</tr>
<tr>
<td align="left" valign="top">X'0F'</td>
<td align="left" valign="top">Red<br>
Blink<br>
Underscore</td>
<td align="left" valign="top">Blink<br>
Underscore<br>
High Intensity</td>
</tr>
<tr>
<td align="left" valign="top">X'10'</td>
<td align="left" valign="top">Turquoise<br>
Column Separator</td>
<td align="left" valign="top">Column Separator</td>
</tr>
<tr>
<td align="left" valign="top">X'11'</td>
<td align="left" valign="top">Turquoise<br>
Column Separator<br>
Reverse Image</td>
<td align="left" valign="top">Column Separator<br>
Reverse Image</td>
</tr>
<tr>
<td align="left" valign="top">X'12'</td>
<td align="left" valign="top">Yellow<br>
Column Separator</td>
<td align="left" valign="top">Column Separator<br>
High Intensity</td>
</tr>
<tr>
<td align="left" valign="top">X'13'</td>
<td align="left" valign="top">Yellow<br>
Column Separator<br>
Reverse Image</td>
<td align="left" valign="top">Column Separator<br>
High Intensity<br>
Reverse Image</td>
</tr>
<tr>
<td align="left" valign="top">X'14'</td>
<td align="left" valign="top">Turquoise<br>
Column Separator<br>
Underscore</td>
<td align="left" valign="top">Column Separator<br>
Underscore</td>
</tr>
<tr>
<td align="left" valign="top">X'15'</td>
<td align="left" valign="top">Turquoise<br>
Column Separator<br>
Reverse Image<br>
Underscore</td>
<td align="left" valign="top">Column Separator<br>
Reverse Image<br>
Underscore</td>
</tr>
<tr>
<td align="left" valign="top">X'16'</td>
<td align="left" valign="top">Yellow<br>
Column Separator<br>
Underscore</td>
<td align="left" valign="top">Column Separator<br>
Underscore</td>
</tr>
<tr>
<td align="left" valign="top">X'17'</td>
<td align="left" valign="top">Pink</td>
<td align="left" valign="top">Blink<br>
Column Separator</td>
</tr>
<tr>
<td align="left" valign="top">X'18'</td>
<td align="left" valign="top">Pink<br>
Reverse Image</td>
<td align="left" valign="top">Blink<br>
Column Separator<br>
Reverse Image</td>
</tr>
<tr>
<td align="left" valign="top">X'19'</td>
<td align="left" valign="top">Blue</td>
<td align="left" valign="top">Blink<br>
Column Separator<br>
High Intensity</td>
</tr>
<tr>
<td align="left" valign="top">X'1A'</td>
<td align="left" valign="top">Blue<br>
Reverse Image</td>
<td align="left" valign="top">Blink<br>
Column Separator<br>
High Intensity<br>
Reverse Image</td>
</tr>
<tr>
<td align="left" valign="top">X'1B'</td>
<td align="left" valign="top">Pink<br>
Underscore</td>
<td align="left" valign="top">Blink<br>
Column Separator<br>
Underscore</td>
</tr>
<tr>
<td align="left" valign="top">X'1C'</td>
<td align="left" valign="top">Pink<br>
Reverse Image<br>
Underscore</td>
<td align="left" valign="top">Blink<br>
Column Separator<br>
Reverse Image<br>
Underscore</td>
</tr>
<tr>
<td align="left" valign="top">X'1D'</td>
<td align="left" valign="top">Blue<br>
Underscore</td>
<td align="left" valign="top">Blink<br>
Column Separator<br>
High Intensity<br>
Underscore</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Border characters</strong></dt>
<dd>INPUT; ARRAY(8) of CHAR(1)
<p> The border characters that define the pop-up window in which the help may
be displayed. The eight array characters are:</p>
<ol>
<li>The character to define the top left corner.</li>
<li>The character to define the top margin.</li>
<li>The character to define the top right corner.</li>
<li>The character to define the left margin.</li>
<li>The character to define the right margin.</li>
<li>The character to define the bottom left corner.</li>
<li>The character to define the bottom margin.</li>
<li>The character to define the bottom right corner.</li>
</ol>
<p>The help window would look like this:</p>
<pre>
12222222222223
4 5
4 5
4 5
67777777777778
</pre>
<p>When using the default values, the border would look like this:</p>
<pre>
..............
: :
: :
: :
:............:
</pre>
</dd>
</dl>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPF3C90 E</td>
<td width="85%" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A24 E</td>
<td align="left" valign="top">Parameter &amp;1 not passed correctly.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A25 E</td>
<td align="left" valign="top">Return code length of &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6Exx E</td>
<td align="left" valign="top">All CPF6Exx messages could be signalled. xx is
from 01 to FF.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R1
<hr>
<table cellpadding="2" cellspacing="2" align="center">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"uim1.htm">User Interface Manager (UIM) APIs</a> | <a href="aplist.htm">APIs by
category</a> </td>
</tr>
</table>
</body>
</html>