401 lines
13 KiB
HTML
401 lines
13 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>Device Selection Exit Program</title>
|
||
|
|
<!-- 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. -->
|
||
|
|
<!-- Begin Header Records ========================================== -->
|
||
|
|
<!-- Created for V5R2 by Donna Saied -->
|
||
|
|
<!-- FLAG REASON LEVEL DATE PGMR COMMENTS -->
|
||
|
|
<!-- $A1 P9A16996 v5r3 090903 AXELO Add what authority is -->
|
||
|
|
<!-- necessary to change this exit-->
|
||
|
|
<!-- point. -->
|
||
|
|
<!-- 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>Device Selection Exit Program</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 65%;">
|
||
|
|
<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="45%">Format name</td>
|
||
|
|
<td align="left" valign="top" width="25%">Input</td>
|
||
|
|
<td align="left" valign="top" width="20%">Char(8)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">Device selection information</td>
|
||
|
|
<td align="left" valign="top">Input/Output</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">Return code</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Exit point name: QIBM_QPA_DEVSEL<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Exit point format name: PADS0100<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
QSYSINC Member Name: EPADSEL<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Device Selection exit program provides an interface to control virtual
|
||
|
|
device selection and automatic creation used by the system for connection
|
||
|
|
requests from clients using virtual device support. The interface allows the
|
||
|
|
user to write an exit program to specify the naming conventions used for
|
||
|
|
automatically created virtual devices and virtual controllers and to specify
|
||
|
|
the automatic creation limit to be used for the specific request.</p>
|
||
|
|
|
||
|
|
<p>The exit program can:</p>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>Reject a specific name for a device connection request.<br><br></li>
|
||
|
|
|
||
|
|
<li>Specify a naming pattern to be used for the automatic creation of a virtual
|
||
|
|
device. This is used only if a specific device name was not requested on the
|
||
|
|
client's connection request.<br><br></li>
|
||
|
|
|
||
|
|
<li>Specify the naming pattern of the virtual controller to be used:
|
||
|
|
<ul>
|
||
|
|
<li>to search in an attempt to select an existing device (if a specific
|
||
|
|
device name was not requested on the client's connection request) or
|
||
|
|
to specify a controller to which to attach the automatically created device.</li>
|
||
|
|
|
||
|
|
<li>This naming pattern is also used to 'count' the
|
||
|
|
number of existing devices toward the automatic creation limit.</li>
|
||
|
|
|
||
|
|
|
||
|
|
<li>Specify a second controller naming pattern to be used to 'count' the number
|
||
|
|
of existing virtual devices.<br><br></li>
|
||
|
|
|
||
|
|
<li>Specify the number of devices that can exist on the virtual controllers
|
||
|
|
whose naming pattern is specified.</li>
|
||
|
|
</ul>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<!-- Section Authorities and Locks was added @A1A -->
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<p>You must have *ALLOBJ authority to register an exit
|
||
|
|
program for the QIBM_QPA_DEVSEL exit point.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Format name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>The format of the information provided in the Device selection information
|
||
|
|
parameter. The format name is <a href="#PDSC0100">PDSC0100</a>.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Device selection information</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT/OUTPUT; CHAR(*)
|
||
|
|
<p>The structure containing the data that is being passed to the exit program
|
||
|
|
and that is returned from the exit program.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Return code</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>Whether to allow the connection request to continue.
|
||
|
|
The possible values are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">0</td>
|
||
|
|
<td align="left" valign="top">Do not allow connection request.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">1</td>
|
||
|
|
<td align="left" valign="top">Allow connection request.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>If any other value is
|
||
|
|
returned, the request for selection and automatic creation of a device
|
||
|
|
description for the client request will be processed using the system defaults
|
||
|
|
for the QAUTOVRT system value and the defaults for the device and controller
|
||
|
|
naming conventions.</p>
|
||
|
|
|
||
|
|
<p>This parameter is initialized to 0 on the call to the exit program.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3><a name="PDSC0100">PDSC0100 Format</a></h3>
|
||
|
|
|
||
|
|
<p>For details about the fields in the following table, see
|
||
|
|
<a href="#fielddes">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 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%">BINARY(4)
|
||
|
|
</td><td align="left" valign="top" width="60%">Size of structure
|
||
|
|
</td></tr><tr>
|
||
|
|
|
||
|
|
<td align="center" valign="top">4
|
||
|
|
</td><td align="center" valign="top">4
|
||
|
|
</td><td align="left" valign="top">BINARY(4)
|
||
|
|
</td><td align="left" valign="top">Function
|
||
|
|
</td></tr><tr>
|
||
|
|
|
||
|
|
<td align="center" valign="top">8
|
||
|
|
</td><td align="center" valign="top">8
|
||
|
|
</td><td align="left" valign="top">BINARY(4)
|
||
|
|
</td><td align="left" valign="top">Specific name requested
|
||
|
|
</td></tr><tr>
|
||
|
|
|
||
|
|
<td align="center" valign="top">12
|
||
|
|
</td><td align="center" valign="top">C
|
||
|
|
</td><td align="left" valign="top">CHAR(10)
|
||
|
|
</td><td align="left" valign="top">Name for requested device
|
||
|
|
</td></tr><tr>
|
||
|
|
|
||
|
|
<td align="center" valign="top">22
|
||
|
|
</td><td align="center" valign="top">16
|
||
|
|
</td><td align="left" valign="top">CHAR(8)
|
||
|
|
</td><td align="left" valign="top">Format of returned data
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<br><br>
|
||
|
|
|
||
|
|
<h3>PDSR0100 Format</h3>
|
||
|
|
|
||
|
|
<p>For details about the fields in the following table, see
|
||
|
|
<a href="#fielddes">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 align="center" valign="bottom">Dec
|
||
|
|
</th><th align="center" valign="bottom">Hex
|
||
|
|
</th></tr><tr>
|
||
|
|
|
||
|
|
<td align="center" valign="top" width="10%">30
|
||
|
|
</td><td align="center" valign="top" width="10%">1E
|
||
|
|
</td><td align="left" valign="top" width="20%">CHAR(2)
|
||
|
|
</td><td align="left" valign="top" width="60%">Reserved
|
||
|
|
</td></tr><tr>
|
||
|
|
|
||
|
|
<td align="center" valign="top">32
|
||
|
|
</td><td align="center" valign="top">20
|
||
|
|
</td><td align="left" valign="top">BINARY(4)
|
||
|
|
</td><td align="left" valign="top">Autocreation limit
|
||
|
|
</td></tr><tr>
|
||
|
|
|
||
|
|
<td align="center" valign="top">36
|
||
|
|
</td><td align="center" valign="top">24
|
||
|
|
</td><td align="left" valign="top">CHAR(6)
|
||
|
|
</td><td align="left" valign="top">Naming pattern for device
|
||
|
|
</td></tr><tr>
|
||
|
|
|
||
|
|
<td align="center" valign="top">42
|
||
|
|
</td><td align="center" valign="top">2A
|
||
|
|
</td><td align="left" valign="top">CHAR(6)
|
||
|
|
</td><td align="left" valign="top">Controller naming pattern for device attachment
|
||
|
|
</td></tr><tr>
|
||
|
|
|
||
|
|
<td align="center" valign="top">48
|
||
|
|
</td><td align="center" valign="top">30
|
||
|
|
</td><td align="left" valign="top">CHAR(6)
|
||
|
|
</td><td align="left" valign="top">Additional controller naming pattern
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<br><br>
|
||
|
|
|
||
|
|
<h3><a name="fielddes">Field Descriptions</a></h3>
|
||
|
|
|
||
|
|
<p><strong>Additional controller naming pattern.</strong> The naming pattern
|
||
|
|
for the controllers to be used for the device automatic creation limit. When
|
||
|
|
applying the check for automatic creation limit, devices attached to these
|
||
|
|
controllers are also counted when determining ifr the limit is exceeded.
|
||
|
|
This field is initialized to blanks before the call is made to the exit program.</p>
|
||
|
|
|
||
|
|
<p><strong>Autocreation limit.</strong> The number to be used for the
|
||
|
|
virtual device automatic creation limit for this connection request.
|
||
|
|
Possible values are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="10 90" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">0</td>
|
||
|
|
<td align="left" valign="top">Do not allow any additional virtual device
|
||
|
|
descriptions to be created automatically.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" nowrap>1-32500</td>
|
||
|
|
<td align="left" valign="top">The number of devices that can be attached to the
|
||
|
|
controller descriptions whose naming patterns are specified in Controller
|
||
|
|
naming pattern for device attachment and Additional controller naming pattern.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">32767</td>
|
||
|
|
<td align="left" valign="top">The special value of *NOMAX. Do not limit the
|
||
|
|
automatic creation of virtual devices.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Controller naming pattern for device attachment.</strong>
|
||
|
|
The naming pattern for the controller to which an automatically created device
|
||
|
|
is to be attached. These characters must be a valid input to the CRTCTLVWS
|
||
|
|
command. If there are not six characters, the pattern is padded with zeros.
|
||
|
|
If the Autocreation limit is 1-32500, the devices attached to controllers
|
||
|
|
with this pattern are counted and this number is used toward the automatic
|
||
|
|
creation limit. This field is initialized to blanks
|
||
|
|
before the call is made to the exit program.</p>
|
||
|
|
|
||
|
|
<p><strong>Format of returned data.</strong> The format name
|
||
|
|
specified by the user exit program for the output data returned from the Device
|
||
|
|
Selection exit point. The only format supported currently is PDSR0100. This
|
||
|
|
field is initialized to PDSR0100 on the call to the exit program.</p>
|
||
|
|
|
||
|
|
<p><strong>Function.</strong> The function being used by the client.
|
||
|
|
Possible values are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">APPC</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
|
<td align="left" valign="top">TELNET</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>3</em></td>
|
||
|
|
<td align="left" valign="top">Virtual Terminal Manager API (VTM API)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Name for requested device.</strong> The name of the device
|
||
|
|
requested by the client. If Specific name requested is
|
||
|
|
set to 0, this field is blank.</p>
|
||
|
|
|
||
|
|
<p><strong>Naming pattern for device.</strong> The naming pattern to be used
|
||
|
|
for device automatic creation. These characters must be a valid input to the
|
||
|
|
CRTDEVDSP command. This field is checked only if the Specific name requested
|
||
|
|
field is 0. This field is initialized to blanks before the call
|
||
|
|
is made to the exit program.</p>
|
||
|
|
|
||
|
|
<p><strong>Reserved.</strong> A reserved field that must be set to hexadecimal
|
||
|
|
zeros.</p>
|
||
|
|
|
||
|
|
<p><strong>Size of structure.</strong> The size of the structure
|
||
|
|
containing the data being passed to and returned from the exit
|
||
|
|
program.</p>
|
||
|
|
|
||
|
|
<p><strong>Specific name requested.</strong> Whether a specific
|
||
|
|
name was requested by the client. If a specific name was
|
||
|
|
requested, this name will be passed to the exit program in the Name for
|
||
|
|
requested device field.</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top">No specific name was requested.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">Specific name was requested.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Coding Guidelines</h3>
|
||
|
|
|
||
|
|
<p>Applications should consider the following when coding this exit program:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The program should return an exception for the requested operation only if
|
||
|
|
there has been a
|
||
|
|
failure in the operation. If the program signals an escape message to the API,
|
||
|
|
the system assumes there is a failure. A diagnostic message is returned to the
|
||
|
|
calling program. The request for selection and automatic creation of a device
|
||
|
|
description for the client request will be processed using the system defaults
|
||
|
|
for the QAUTOVRT system value and the defaults for the device and controller
|
||
|
|
naming conventions.<br><br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The program must clean up any locks that it acquires.<br><br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The program must handle all potential error conditions associated with
|
||
|
|
its own operations (be fault tolerant).<br><br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The program must avoid infinite looping conditions.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
Exit program introduced: V5R2
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"misc1.htm">Miscellaneous APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|