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

733 lines
19 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>Handle CD-ROM Premastering State (QLPCDRST, QlpHandleCdState)
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. -->
<!-- QLPCDRST SCRIPT A converted by B2H R4.1 (346) (CMS) by KENTALA -->
<!-- at RCHVMW2 on 7 Oct 1998 at 18:30:49 -->
<!-- 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>Handle CD-ROM Premastering State (QLPCDRST, QlpHandleCdState) 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%">Qualified user space name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">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">Current CD-ROM premastering state</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Distribution set map identifier used</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Requested CD-ROM premastering state</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Distribution set map identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Option</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</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: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Service Program: QLPCDROM<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Handle CD-ROM Premastering State (OPM, QLPCDRST; ILE, QlpHandleCdState)
API allows you to do the following:</p>
<ul>
<li>Enable the job for CD-ROM premastering. (<strong>Note:</strong>
Premastering is the set of activities done in preparation for creating a master
image as a template for manufacturing a number of copies of a CD-ROM.)
<p>When the job is in this state, all save operations (SAVOBJ, SAVLIB,
SAVLICPGM, SAV, SAVDLO, SAVSYS, and so forth) result in information being
stored away about the sizes of these tape files. This information is then used
as input for the Generate CD-ROM Premastering Information (QLPCDINF,
QlpGenCdPremasteringInfo) API when it generates the QDSETMAP byte-stream file.
See the description of the Generate CD-ROM Premastering Information API for an
explanation of the QDSETMAP byte-stream file. Also, the following occurs:</p>
<ul>
<li>During a SAVSYS operation, special files are saved to tape that are needed
on the CD-ROM when you try to perform an installation.</li>
<li>Tape-write error protection is turned off during the save operations.</li>
</ul>
</li>
<li>Disable the job for CD-ROM premastering
<p>Place the job back into a state where all save operations work as before.
There are two options that can be used when disabling the job for CD-ROM
premastering.</p>
<ul>
<li>Leave the current information about the files saved during this job as is.
<p>This option gives you the ability to enable the job again later to continue
save operations for a given set of CD-ROMs.</p>
<p>Signing off or ending your job is equivalent to performing this option.</p>
</li>
<li>Erase the current information about the files saved during this job.
<p>This option removes all existing information about any save operations done
during this job. The next time you enable your job for CD-ROM premastering,
there will be no information about this set CD-ROMs.</p>
</li>
</ul>
</li>
<li>Query the current CD-ROM premastering job state</li>
</ul>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*EXCLUDE</dd>
<dt><em>QSYS Library Authority</em></dt>
<dd>*CHANGE</dd>
<dt><em>User Space Authority</em></dt>
<dd>*CHANGE</dd>
<dt><em>User Space Library Authority</em></dt>
<dd>*USE</dd>
<dt><em>User Space Lock</em></dt>
<dd>*EXCLRD</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Qualified user space name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The user space that receives the generated list and the library in which it
is located. The first 10 characters contain the user space name, and the second
10 characters contain the library name.</p>
<p>The following special value is allowed for the user space name:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*NONE</em></td>
<td align="left" valign="top">No information about tape files that are saved
when a job was enabled for CD-ROM premastering are returned.</td>
</tr>
</table>
<br>
<p>The following special values are allowed 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 current library is used to locate the user
space. If there is no current library, QGPL (general purpose library) is
used.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list is used to locate the user
space.</td>
</tr>
<tr>
<td align="left" valign="top"></td>
<td align="left" valign="top">This parameter must be blank when the requested
CD-ROM premastering state parameter is not -1.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The content and format of the information returned.</p>
<p>The possible format name follows:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>TPFL0100</em></td>
<td align="left" valign="top">The list of tape files that are saved when the
job was enabled for CD-ROM premastering</td>
</tr>
<tr>
<td align="left" valign="top"></td>
<td align="left" valign="top">For more information, see <a href=
"#HDRTAPFSV">TPFL0100 List Data Section</a>. This parameter must be blank when
the requested CD-ROM premastering state parameter is not -1.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Current CD-ROM premastering state</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The variable that receives the current CD-ROM premastering state.</p>
<p>The possible values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The job is not enabled for CD-ROM
premastering</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The job is enabled for CD-ROM premastering</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Distribution set map identifier used</strong></dt>
<dd>OUTPUT; CHAR(10)
<p>The variable that receives the distribution set map identifier for the set
of tapes currently being premastered.</p>
</dd>
<dt><strong>Requested CD-ROM premastering state</strong></dt>
<dd>INPUT; BINARY(4)
<p>The CD-ROM premastering state that the job should be set to.</p>
<p>The possible values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Disable the job for CD-ROM premastering without
destroying the information about the tape files that have been saved.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Enable the job for CD-ROM premastering.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Disable the job for CD-ROM premastering and also
destroy all information about tape files that have been saved.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">Return the current CD-ROM premastering job state
and the distribution set map identifier that are being used in the output
parameters.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Distribution set map identifier</strong></dt>
<dd>INPUT; CHAR(10)
<p>The distribution set map identifier that uniquely establishes this set of
CD-ROMs being premastered.</p>
<p>This name can only include the following characters:</p>
<ul>
<li>Uppercase characters (A-Z)</li>
<li>Numeric characters (0-9)</li>
<li>Underscore character (_)</li>
</ul>
<br>
<p>This parameter must be blank when the requested CD-ROM premastering state
parameter is not 1.</p>
</dd>
<dt><strong>Option</strong></dt>
<dd>INPUT; BINARY(4)
<p>Whether to create new information about this particular set of CD-ROMs or to
add information to a set of CD-ROMs. This parameter must be 0 when the
requested CD-ROM premastering state parameter is not 1.</p>
<p>The possible values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Start over with new information about CD-ROM
premastering. If existing information is found about this set of CD-ROMs, the
information will be erased.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Add information about CD-ROM premastering. If
existing information is found about this set of CD-ROMs, it continues to be
used and any future save operations that are done during this job are added to
it.</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="HDRTPSLIST">Format of the Generated List</a></h3>
<p>The file member list consists of the following:</p>
<ul>
<li>A user area</li>
<li>A generic header</li>
<li>An input parameter section</li>
<li>A header section</li>
<li>A list data section:
<ul>
<li>TPFL0100 format</li>
</ul>
</li>
</ul>
<p>For details about the user area and generic header, see <a href="../apiref/apiexmp.htm">API
examples</a>. For details about
the remaining items, see the following sections. For detailed descriptions of
the fields in the list returned, see <a href="#HDRTPSVDE">Field
Descriptions</a>.</p>
<p>When you retrieve list entry information from a user space, you must use the
entry size returned in the generic header. The size of each entry may be padded
at the end. If you do not use the entry size, the result may not be valid. For
examples of how to process lists, see <a href="../apiref/apiexmp.htm">API
examples</a>.</p>
<br>
<h3>Input Parameter Section</h3>
<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%">User space name specified</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">User space library name specified</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Format name specified</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Requested CD-ROM premastering state</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">Option</td>
</tr>
<tr>
<td align="center" valign="top">36</td>
<td align="center" valign="top">24</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Distribution set map identifier</td>
</tr>
</table>
<br>
<br>
<h3>Header Section</h3>
<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%">User space name used</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">User space library name used</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRTAPFSV">TPFL0100 List Data Section</a></h3>
<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(17)</td>
<td align="left" valign="top" width="60%">Tape file label</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRTPSVDE">Field Descriptions</a></h3>
<p><strong>Distribution set map identifier.</strong> The distribution set map
identifier that was specified in the call to the API.</p>
<p><strong>Format name specified.</strong> The format name that was passed to
this API on the call in the format name parameter.</p>
<p><strong>Option.</strong> The option that was passed to this API on the call
in the option parameter.</p>
<p><strong>Requested CD-ROM premastering state.</strong> The requested CD-ROM
premastering state that was specified in the call to the API.</p>
<p><strong>Tape file label.</strong> The name of the tape file that was saved
to tape.</p>
<p><strong>User space library name specified.</strong> The name of the user
space library as specified on the call to the API.</p>
<p><strong>User space library name used.</strong> The actual name of the
library where this user space was found.</p>
<p><strong>User space name specified.</strong> The name of the user space as
specified on the call to the API.</p>
<p><strong>User space name used.</strong> The actual name of the user space
used to store the data listed.</p>
<br>
<h3>Error Messages</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">CPF3C1E E</td>
<td align="left" valign="top">Required parameter &amp;1 omitted.</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">CPF3C36 E</td>
<td align="left" valign="top">Number of parameters, &amp;1, entered for this
API was 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">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3D9B E</td>
<td align="left" valign="top">Requested CD-ROM premastering state not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3D9C E</td>
<td align="left" valign="top">Option &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3D9E E</td>
<td align="left" valign="top">Distribution set map identifier &amp;1 is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3DA2 E</td>
<td align="left" valign="top">&amp;1 parameter is not blank.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3DA3 E</td>
<td align="left" valign="top">&amp;1 parameter is not 0.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9801 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 E</td>
<td align="left" valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9803 E</td>
<td align="left" valign="top">Cannot allocate object &amp;2 in library
&amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9804 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9807 E</td>
<td align="left" valign="top">One or more libraries in library list
deleted.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9808 E</td>
<td align="left" valign="top">Cannot allocate one or more libraries on library
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9820 E</td>
<td align="left" valign="top">Not authorized to use library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9830 E</td>
<td align="left" valign="top">Cannot assign library &amp;1.</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: V3R6
<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>