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

573 lines
16 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>Request License (QLZAREQ) 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. -->
<!-- QLZAREQ SCRIPT A converted by B2H R4.1 (346) (CMS) by KENTALA at -->
<!-- RCHVMW2 on 7 Oct 1998 at 19:51:28 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Edited by Kersten Jan 02 -->
<!--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>Request License (QLZAREQ) 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%">Product identification</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">Product identification format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">License user</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">License user format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</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;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Request License (QLZAREQ) API requests the use of a product that has
been packaged for licensed use. Multiple uses of a product may be requested
with a single call to this API. The request causes the usage count to be
compared with the usage limit. The uses are assigned to the name that is
specified in the license user parameter. The uses remain assigned to the
license user until they are released (see</p>
<p><strong>Note:</strong> It is suggested that before a Request License
(QLZAREQ) is done, the application retrieves the product information handle
using the Retrieve License Information API (QLZARTV). The application should
then compare this handle with the handle passed back at Add Product License
Information time. It should compare the two values before the Request is done.
If the handles do not match, the product has been tampered with. This process
helps to ensure asset protection.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Public API Authority</em></dt>
<dd>*EXCLUDE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Product identification</strong></dt>
<dd>INPUT; CHAR(*)
<p>Information that uniquely identifies the product or feature whose licensed
use is requested. The structure of this information is determined by the name
of the format.</p>
</dd>
<dt><strong>Product identification format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The name of the format that describes the product identification.</p>
<p>The only format name supported is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>LICP0100</em></td>
<td align="left" valign="top">This format identifies the product ID, release
level, and feature whose use is requested. See <a href="#HDRLRQ0100">LICP0100
Format</a>.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>License user</strong></dt>
<dd>INPUT; CHAR(*)
<p>The name to which use of the license product is assigned and tracked.</p>
</dd>
<dt><strong>License user format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The name of the format that describes the license user information.</p>
<p>The formats supported are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>LICL0100</em></td>
<td align="left" valign="top">This format identifies the license user to be
requested. See <a href="#HDRLICL10X">LICL0100 Format</a>.</td>
</tr>
<tr>
<td align="left" valign="top"><em>LICL0200</em></td>
<td align="left" valign="top">This format identifies the license user being
requested and the multiple uses (number of uses) for each license user. See <a
href="#HDRLRQ0300">LICL0200 Format</a>.</td>
</tr>
</table>
<br>
</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="HDRLRQ0100">LICP0100 Format</a></h3>
<p>For a detailed description of the fields in this table, see <a href=
"#HDRLICP01">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%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Product ID</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="center" valign="top">7</td>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Release</td>
</tr>
<tr>
<td align="center" valign="top">13</td>
<td align="center" valign="top">D</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Feature</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRLICL10X">LICL0100 Format</a></h3>
<p>For a detailed description of the field in this table, see <a href=
"#HDRLICP01">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%">CHAR(10)</td>
<td align="left" valign="top" width="60%">License user</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRLRQ0300">LICL0200 Format</a></h3>
<p>For a detailed description of the fields in this table, see <a href=
"#HDRLICP01">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%">Offset to license user</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">Length of license user</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">License user handle</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to additional license user
information</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of additional license user
information</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> Use the offset
to license user field to determine the offset.</td>
</tr>
<tr>
<td align="center" valign="top"></td>
<td align="center" valign="top"></td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">License user</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> Use the offset
to additional license user information field to determine the offset.</td>
</tr>
<tr>
<td align="center" valign="top"></td>
<td align="center" valign="top"></td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of uses requested</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRLICP01">Field Descriptions</a></h3>
<p><strong>Feature.</strong> The feature of the product. Valid values for the
feature are 5001 through 9999.</p>
<p><strong>Length of additional license user information.</strong> The length
of the additional license user information. Set this field to 0 if there is no
additional license user information.</p>
<p><strong>License user.</strong> The license user being requested. For
registered use, specify the nonblank name you want assigned as the license
user. For concurrent use, specify *JOB. For processor use, specify
*PROCESSOR.</p>
<p><strong>License user handle.</strong> This value is passed in by the vendor
at the time of the Request License (QLZAREQ) API call. When the vendor wants to
release the user, this handle must be specified on the Release License
(QLZARLS) API call. This value many be any eight character field, including
blanks. If the value specified on the release call does not match the value
initially specified on the request call, the license user is not released. This
field is never displayed or output through any license management interfaces
and is only known to the vendor application.</p>
<p><strong>Length of license user.</strong> The length of the license user
field. This may be a value 1 through 80. This value may only change within the
same license term if there are no current users at the time the change request
is made. To conserve space, use the smallest value necessary for this
length.</p>
<p><strong>Number of uses requested.</strong> The number of license uses being
requested for this license user. This value must be between 1 and 999 999. If
this field is not specified, the number of uses requested is 1.</p>
<p><strong>Offset to additional license user information.</strong> The offset
from the beginning of the license user information to the additional
information for the first license user. Specify 0 for this field if there is no
additional information for the license user.</p>
<p><strong>Offset to license user.</strong> The offset from the beginning of
the license user information to the first license user.</p>
<p><strong>Product ID.</strong> The product ID of the product or feature whose
licensed use is requested.</p>
<p><strong>Release level.</strong> The version, release, and modification level
of the product or feature. The release level must be a valid special value, or
the release level must be in the format V<em>x</em>R<em>y</em>M<em>z</em>.
Valid values for <em>x</em> and <em>y</em> are 0 through 9. Valid values for
<em>z</em> are 0 through 9 and A through Z.</p>
<p>The valid special value is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*ONLY</em></td>
<td align="left" valign="top">The release level is determined by searching the
system for a given product. The release level is taken from the product
definition. This value is not valid if more than one product definition exists
for the same product ID.</td>
</tr>
</table>
<p><strong>Reserved.</strong> Reserved for future use. This field must be set
to hexadecimal zeros.</p>
<br>
<h3><a name="HDRREQERR">Error Messages</a></h3>
<table 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">CPF24B4 E</td>
<td width="85%" valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E1C E</td>
<td align="left" valign="top">License user parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E1E E</td>
<td align="left" valign="top">Length of license user is not correct.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E1F E</td>
<td align="left" valign="top">Attempt made to change length of the license
user, resulting code &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E11 E</td>
<td align="left" valign="top">License information not retrieved.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E12 E</td>
<td align="left" valign="top">License information not available.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E13 E</td>
<td align="left" valign="top">More than one release found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E15 E</td>
<td align="left" valign="top">Error in license management function.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E17 E</td>
<td align="left" valign="top">Usage limit exceeded for product &amp;1. User
added.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E18 E</td>
<td align="left" valign="top">Attempt made to exceed usage limit for product
&amp;1. User not added.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E70 E</td>
<td align="left" valign="top">Grace period expired. Requesting user already
added.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E71 E</td>
<td align="left" valign="top">Grace period expired. Requesting user not
added.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E72 E</td>
<td align="left" valign="top">Usage limit of &amp;4 exceeded. Grace period will
expire in &amp;6 days on &amp;5.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E73 E</td>
<td align="left" valign="top">Expiration date &amp;4 was reached.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E78 E</td>
<td align="left" valign="top">The license key for product &amp;1, license term
&amp;2, feature &amp;3 is no longer valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E79 E</td>
<td align="left" valign="top">Cannot specify different number of uses than
already requested.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9E91 E</td>
<td align="left" valign="top">License user &amp;1 is not valid.</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>
<tr>
<td align="left" valign="top">CPI9E75 I</td>
<td align="left" valign="top">Grace period will expire in &amp;5 days on
&amp;4.</td>
</tr>
<tr>
<td align="left" valign="top">CPI9E76 I</td>
<td align="left" valign="top">Expiration date will be reached in &amp;5 days on
&amp;4.</td>
</tr>
<tr>
<td align="left" valign="top">CPI9E77 I</td>
<td align="left" valign="top">License key will not be valid in &amp;8 days on
&amp;9.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R3
<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=
"sw1.htm">Software Product APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</body>
</html>