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

804 lines
23 KiB
HTML
Raw Permalink 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>Retrieve Subsystem Information (QWDRSBSD) 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. -->
<!-- WM SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- File cleanup completed Novt 2001 by v2cdijab -->
<!-- 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>Retrieve Subsystem Information (QWDRSBSD) 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%">Receiver variable</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of receiver variable</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">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">4</td>
<td align="left" valign="top">Qualified subsystem name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</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;Optional Parameter:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">6</td>
<td align="left" valign="top" width="50%">Number of qualified subsystem
libraries</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve Subsystem Information (QWDRSBSD) API retrieves information
about one or more specific subsystems or all active subsystems.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Subsystem Description Authority</em></dt>
<dd>*USE</dd>
<dt><em>Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Subsystem Description Lock</em></dt>
<dd>*EXCLRD</dd>
</dl>
<p>The subsystem description authority and library authority are not required
when *ACTIVE is specified for the qualified subsystem name parameter.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The variable to receive the subsystem information. This area must be large
enough to accommodate the information specified.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable. The length must be at least 8 bytes. If
the variable is not long enough to hold the subsystem information, the data is
truncated.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the subsystem information. You can use this format:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>SBSI0100</em></td>
<td align="left" valign="top">Basic subsystem information. For details, see <a
href="#HDRSBSI01">SBSI0100 Format</a>.</td>
</tr>
<tr>
<td align="left" valign="top"><em>SBSI0200</em></td>
<td align="left" valign="top">Multiple subsystems information. For details, see
<a href="#HDRSBSI02">SBSI0200 Format</a>. This format name must be specified if
*ACTIVE is specified in the first 10 characters of the qualified subsystem name
or if the number of qualified subsystem names parameter is greater than 1.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Qualified subsystem name</strong></dt>
<dd>INPUT; ARRAY(*) of CHAR(20)
<p>An array of CHAR(20) values giving the names of the subsystems about which
to retrieve information and the library in which the subsystem description is
located. The number of qualified subsystem names parameter specifies how many
elements are in this array.</p>
<p>The first 10 characters contain the subsystem name. You can use the
following special value for the subsystem name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*ACTIVE</em></td>
<td align="left" valign="top">Return information about all active subsystems.
If *ACTIVE is specified for the first 10 characters:
<ul>
<li>SBSI0200 must be specified for the format name parameter.</li>
<li>the value in the second 10 characters must be blank.</li>
</ul>
</td>
</tr>
</table>
<p>The second 10 characters contain the library name. You can use one of 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>
<p>If *ACTIVE is specified in the first 10 characters, the value in the second
10 characters must be blank.</p>
<p>If information for a subsystem description is requested more than once in
the array, the receiver variable will not contain duplicate information for
that subsystem description.</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>
<br>
<h3>Optional Parameter</h3>
<dl>
<dt><strong>Number of qualified subsystem names</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of names specified in the qualified subsystem name parameter. If
this parameter is not specified, the number of names specified defaults to 1.
If this parameter is specified, the number specified must be in the range 1 to
65535. If a number greater than 1 is specified, SBSI0200 must be specified for
the format name parameter.</p>
</dd>
</dl>
<br>
<h3><a name="HDRSBSI01">SBSI0100 Format</a></h3>
<p>The following table shows the information returned in the receiving variable
for the SBSI0100 format. For a detailed description of each field, see <a href=
"#HDRSBSIFD">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%">Bytes returned</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">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Subsystem description name</td>
</tr>
<tr>
<td align="center" valign="top">18</td>
<td align="center" valign="top">12</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Subsystem description library name</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Subsystem status</td>
</tr>
<tr>
<td align="center" valign="top">38</td>
<td align="center" valign="top">26</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Sign-on device file name</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Sign-on device file library name</td>
</tr>
<tr>
<td align="center" valign="top">58</td>
<td align="center" valign="top">3A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Secondary language library name</td>
</tr>
<tr>
<td align="center" valign="top">68</td>
<td align="center" valign="top">44</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Maximum active jobs</td>
</tr>
<tr>
<td align="center" valign="top">72</td>
<td align="center" valign="top">48</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Currently active jobs</td>
</tr>
<tr>
<td align="center" valign="top">76</td>
<td align="center" valign="top">4C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of storage pools defined</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="5" colspan="2">Offsets vary. These five
fields repeat, in the order listed, for each pool defined for the
subsystem.</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Pool ID</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Pool name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Pool size</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Pool activity level</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRSBSI02">SBSI0200 Format</a></h3>
<p>The following table shows the information returned in the receiving variable
for the SBSI0200 format. For a detailed description of each field, see <a href=
"#HDRSBSIFD">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%">Bytes returned</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">Bytes available</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">Offset to first subsystem entry</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of subsystem entries returned</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">Size of a subsystem entry</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="10" colspan="2">Offsets vary. These
fields repeat, in the order listed, for each subsystem.</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Subsystem description name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Subsystem description library name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(12)</td>
<td align="left" valign="top">Subsystem extended status</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Maximum active jobs</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Currently active jobs</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Subsystem monitor job name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Subsystem monitor job user</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Subsystem monitor job number</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(50)</td>
<td align="left" valign="top">Subsystem description text</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRSBSIFD">Field Descriptions</a></h3>
<p><strong>Bytes available.</strong> The total length of all data
available.</p>
<p><strong>Bytes returned.</strong> The length of the data actually returned.
The number of bytes returned is always less than or equal to both the number of
bytes available and the receiving variable length.</p>
<p><strong>Currently active jobs.</strong> The number of jobs currently active
in the subsystem. This number <em>includes</em> held jobs but <em>excludes</em>
jobs that are disconnected or suspended because of a transfer secondary job or
a transfer group job. If the subsystem status is *INACTIVE, this number is
0.</p>
<p><strong>Maximum active jobs.</strong> The maximum number of jobs that can
run or use resources in the subsystem at one time. If the subsystem description
specifies *NOMAX, indicating that there is no maximum, this number is -1.</p>
<p><strong>Number of subsystem entries returned.</strong> The number of
subsystems for which entries are returned. This number determines how many
times the entire set of fields describing a subsystem is repeated.</p>
<p><strong>Number of storage pools defined.</strong> The number of storage
pools defined for the subsystem. The maximum number of storage pools for a
subsystem is currently 10. This number determines how many times the pool ID,
pool name, pool size, pool activity level, and reserved fields are repeated.
Those five fields are repeated as a group for each pool defined for the
subsystem.</p>
<p><strong>Offset to first subsystem entry.</strong> The number of bytes from
the first byte of the receiver variable to the information for the first
subsystem.</p>
<p><strong>Pool activity level.</strong> The maximum number of jobs that can be
active in the pool at one time. If the pool name indicates a system-defined
pool, the number returned is 0.</p>
<p><strong>Pool ID.</strong> The pool ID for the subsystem pool.</p>
<p><strong>Pool name.</strong> The name of the subsystem pool. If the pool is
user-defined, the value of this field is *USERPOOL. If the pool is
system-defined, the value is one of these names:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*BASE</em></td>
<td align="left" valign="top">The system base pool, which can be shared with
other subsystems. The QBASPOOL system value defines the base pool's minimum
size. The base pool contains all main storage not allocated to other pools. The
QBASACTLVL system value defines its activity level.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*INTERACT</em></td>
<td align="left" valign="top">The shared pool used for interactive work.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NOSTG</em></td>
<td align="left" valign="top">No storage size or activity level is assigned to
this storage pool.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*SHRPOOL1-*SHRPOOL60</em></td>
<td align="left" valign="top">Shared pools.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*SPOOL</em></td>
<td align="left" valign="top">The shared pool for spooling writers.</td>
</tr>
</table>
<p>The Change Shared Storage Pool (CHGSHRPOOL) command specifies the size and
activity level of shared pools.</p>
<p><strong>Pool size.</strong> If the pool name is *USERPOOL, the amount of
storage, in kilobytes, that the pool attempts to allocate. If the pool has any
other name, the value of this field is 0.</p>
<p><strong>Reserved.</strong> An ignored field.</p>
<p><strong>Secondary language library name.</strong> The name of the
subsystem's secondary language library.</p>
<p><strong>Sign-on device file library name.</strong> The name of the library
in which the sign-on device file resides.</p>
<p><strong>Size of a subsystem entry.</strong> The number of bytes in the entry
for a subsystem.</p>
<p><strong>Subsystem description library name.</strong> The name of the library
in which the subsystem description resides.</p>
<p><strong>Subsystem description name.</strong> The name of the subsystem about
which information is being returned.</p>
<p><strong>Subsystem description text.</strong> The text description of the
subsystem description. The field is blank if there is no text description.</p>
<p><strong>Subsystem extended status.</strong> Possible values that can be
returned for subsystem extended status are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*ACTIVE</em></td>
<td align="left" valign="top">The subsystem is running.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*ENDING</em></td>
<td align="left" valign="top">An ENDSBS command has been issued for the
subsystem or an ENDSYS command has been issued, but the subsystem is still
running.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*INACTIVE</em></td>
<td align="left" valign="top">The subsystem is not running.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*RESTRICTED</em></td>
<td align="left" valign="top">An ENDSBS command for the controlling subsystem,
an ENDSYS *ALL command, or an ENDSYS command has placed the controlling
subsystem in a restricted condition.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*STARTING</em></td>
<td align="left" valign="top">A STRSBS command has been issued for the
subsystem, but it is still in the process of being started.</td>
</tr>
</table>
<p><strong>Subsystem monitor job name.</strong> The name for the subsystem
monitor job as identified to the system. The field is blank if the subsystem
extended status field is *INACTIVE.</p>
<p><strong>Subsystem monitor job number.</strong> The system-assigned number
for the subsystem monitor job. The field is blank if the subsystem extended
status field is *INACTIVE.</p>
<p><strong>Subsystem monitor job user.</strong> The name of the user profile
under which the subsystem monitor job is running. The field is blank if the
subsystem extended status field is *INACTIVE.</p>
<p><strong>Subsystem status.</strong> Possible values that can be returned for
subsystem status are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*ACTIVE</em></td>
<td align="left" valign="top">The subsystem is running.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*INACTIVE</em></td>
<td align="left" valign="top">The subsystem is not running.</td>
</tr>
</table>
<br>
<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 align="left" valign="top" width="15%">CPF1605 E</td>
<td align="left" valign="top" width="85%">Cannot allocate subsystem description
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1606 E</td>
<td align="left" valign="top">Error during allocation of subsystem &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1607 E</td>
<td align="left" valign="top">Previous request pending for subsystem
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1608 E</td>
<td align="left" valign="top">Subsystem description &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1619 E</td>
<td align="left" valign="top">Subsystem description &amp;1 in library &amp;2
damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1835 E</td>
<td align="left" valign="top">Not authorized to subsystem description.</td>
</tr>
<tr>
<td align="left" valign="top">CPF187A E</td>
<td align="left" valign="top">List of active subsystems not available.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1877 E</td>
<td align="left" valign="top">Incorrect format specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1878 E</td>
<td align="left" valign="top">Library name not valid for subsystem &amp;1.</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">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C3A E</td>
<td align="left" valign="top">Value for parameter &amp;2 for API &amp;1 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">CPF8122 E</td>
<td align="left" valign="top">&amp;8 damage on library &amp;4.</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">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: V2R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top">Top</a> | <a href="wm1.htm">
Work Management APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>