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

502 lines
23 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>DMConfigurationScript Introduction</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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head><body>
<!--Java sync-link-->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Introduction to using Hardware Configuration Markup Languages</h2>
<p>
<a href="#lpardm"><strong>Logical Partitions and Disk Management</strong></a><br>
<a href="#procord"><strong>Processing order</strong></a><br>
<a href="#actint"><strong>The Action interface</strong></a><br>
<a href="#infint"><strong>The Information interface</strong></a><br>
<a href="#statint"><strong>The Status interface</strong></a><br>
<a href="#msgs"><strong>Messages</strong></a><br>
<a href="#valxml"><strong>Validation of the XML</strong></a><br>
<a href="#version"><strong>Version</strong></a><br>
<a href="#terms"><strong>Terminology</strong></a>
</p>
<h2><a name="lpardm">Logical Partitions and Disk Management</a></h2>
<p>Logical Partition Markup Language (LPML) is defined as
LPARConfigurationScript.
Disk Management Markup Language (DMML) is defined as DMConfigurationScript.</p>
<p>To work with Logical Partitions or Disk Management in V5R1 or later, new XML
based languages are being provided. These new interfaces provide the ability
to view current configuration information, change configurations, and check the
status of configuration change requests. Before you can use these interfaces,
it is necessary to understand how Logical Partitioning or Disk Management
works. Once you have this information, this document will explain how to write
XML to build requests to send to the server and interpret the results
returned.</p>
<p>Both DMConfigurationScript and LPARConfigurationScript use the same design.
This design breaks requests and responses into three types: Informational,
Status, and Action. These three types are identified by the tags &lt;Info&gt;,
&lt;Status&gt;, and &lt;Action&gt; respectively. A single
<strong>request</strong> or <strong>response</strong> may consist of one or
more of these types in no particular order. The format for all data sent should
have this basic structure:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Action&gt;</samp><br>
<samp> &lt;!-- Requests to perform a configuration change go here
--&gt;</samp><br>
<samp> &lt;/Action&gt;</samp></p>
<p><samp> &lt;Info&gt;</samp><br>
<samp> &lt;!-- Requests for information about the current configuration go
here --&gt;</samp><br>
<samp> &lt;/Info&gt;</samp></p>
<p><samp> &lt;Status&gt;</samp><br>
<samp> &lt;!-- Requests for information about the status of a
configuration</samp><br>
<samp> change request goes here --&gt;</samp><br>
<samp> &lt;/Status&gt;</samp></p>
<p><samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>The format for data returned may look like:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp> &lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp></p>
<p><samp> &lt;Action&gt;</samp><br>
<samp> &lt;!-- will contain ActionProfile with request results
--&gt;</samp><br>
<samp> &lt;/Action&gt;</samp></p>
<p><samp> &lt;Info&gt;</samp><br>
<samp> &lt;!-- will contain Information Requested
--&gt;</samp><br>
<samp> &lt;/Info&gt;</samp></p>
<p><samp> &lt;Status&gt;</samp><br>
<samp> &lt;!-- will contain Status information requested
--&gt;</samp><br>
<samp> &lt;/Status&gt;</samp></p>
<p><samp>&lt;/DMConfigurationScript&gt;</samp><br>
</p>
<h2><a name="procord">Processing order</a></h2>
<p>In general, tags are processed in the order in which they are listed in the
script. Thus, a <strong>script</strong> may include an Status
<strong>request</strong> (a), followed by an Info <strong>request</strong> (b),
followed by another Status <strong>request</strong> (c). The requests will be
processed and responded to in the order they were received (a, b, c). Action
requests are processed slightly differently. (See Processing order in
<a href="#actint">The Action interface</a>.)<br>
</p>
<h2><a name="actint">The Action interface</a></h2>
<p>Any <strong>request</strong> for a configuration change is requested as an
action. For LPAR actions, the <strong>user</strong> must explicitely send an
<samp>&lt;CommitActions&gt;</samp> request in order to commit any previously
requested actions. If a <samp>&lt;CloseSession&gt;</samp> is requested before
an action is committed, all requested changes will be lost. No such tag is
necessary for Disk Management. The following are the guidelines for using an
action.<br>
</p>
<ul>
<li><strong>The &lt;OpenSession&gt; action tag.</strong> To avoid multiple
users making conflicting changes to an <strong>system</strong>, only one
<strong>user</strong> at a time may have the action interface open on a
system. To open the interface, the &lt;OpenSession&gt; tag is used. Once the
action interface is successfully opened, a handle will be returned. All
subsequent action requests must provide this handle. The action interface will
stay open for the <strong>user</strong> until one of the following conditions
occurs:</li>
<li style="list-style: none">
<ul>
<li>The <strong>user</strong> issues a &lt;CloseSession&gt; action request.<br></li>
<li>A severe error occurs on the <strong>system</strong> or the
<strong>system</strong> is restarted. In either case, the action interface
will be closed.<br></li>
<li>The <strong>user</strong> does not send any <strong>request</strong>
containing the handle within 5 minutes. This 5 minute timer is not running
when an action is currently running, unless that action is paused. The timer
is reset to 5 minutes when the <strong>user</strong> sends a status
<strong>request</strong> containing the handle or the <strong>user</strong>
requests additional actions. One way to guarantee the <strong>session</strong>
remains open is to start a thread on the <strong>user</strong> system that
sends a status <strong>request</strong> containing the handle every 3 minutes.
As long as this thread does not end, the <strong>session</strong> will remain
open.<br></li>
</ul>
<p>The status of an action can be one of the following: </p>
<ul>
<li>Pending: The action has been submitted and validated, but has not started
running yet.</li>
<li>Running: The action is currently running. Only one action may be running at
a time.</li>
<li>Paused: The action is waiting for feedback from the user.</li>
<li>Successful: The action completed successfully.</li>
<li>Failed: The action completed unsuccessfully.</li>
<li>Purged: The action was not run because a preceding action was canceled or
failed.</li>
<li>Canceled: The action was canceled by the user.</li>
</ul>
<br>
</li>
<li><strong>The &lt;CloseSession&gt; action tag.</strong> To close the action
interface, use the &lt;CloseSession&gt; action tag. The close should always be
done to allow other users to access the action interface. Other users will be
able to access the action interface after a 5 minute time-out if the close is
not performed, but this timer interface is designed for communications line
failure or <strong>client</strong> failure, and not as a standard exit
mechanism.<br><br></li>
<li><strong>Paused processing.</strong> When an action is running, there may
be warnings or other information that needs to be provided to the
<strong>user</strong> before the action can complete. This will result in the
action pausing and waiting for the <strong>user</strong> to respond. By
checking the status of the action, the <strong>client</strong> can determine if
the current action is paused. Additional information in the message sub tag
for status will explain why the action is paused. The <strong>client</strong>
then has the choice to continue processing the action &lt;ContinueAction&gt;,
cancel the action &lt;CancelAction&gt;, or close the action interface
&lt;CloseSession&gt;.<br><br></li>
<li><strong>Processing order.</strong> All actions are processed in the order
in which they are listed in the script. Once a set of actions are submitted in
a script, no additional actions may be requested in a second script until all
the actions from the first <strong>script</strong> have completed or have been
canceled. Actions will not be processed until all action requests in the
<strong>script</strong> have been verified and any Status or Info requests have
been processed. The <strong>response</strong> from each action
<strong>request</strong> is an action profile &lt;ActionProfile&gt;. This
action profile contains either an action id that can be used to check the
status of the action or the completion status of the action. If an action id
is provided, the action has been enqueued in an action processor in pending
status, changed to running status when the preceding actions have completed
processing, and finally be given a completion status. The
<strong>script</strong> will be completely processed before any pending action
will start running. While running, the status of an action may include
information about the percent done and the stage of the action.<br><br></li>
<li><strong>Errors.</strong> If an action fails for any reason, all subsequent
action requests will not be attempted. For example, if the
<strong>user</strong> requests 5 actions within one script, and the 3rd action
does not complete, the 4th and 5th will not be attempted. If the
<strong>client</strong> wants to run these two actions after the failure, the
4th and 5th must be re-requested in a new script.<br><br></li>
<li><strong>Action stacking.</strong> The <strong>client</strong> may send a
<strong>script</strong> with up to 512 action requests. However until all the
actions of a particular script have completed, the server will return an error
if any further requests are made. An exception to this is the
&lt;CancelAction&gt; request, which may be processed while other actions are
running. As mentioned above, the &lt;CloseSession&gt; tag may also be processed
while an action is running, however it will have no effect until all enqueued
actions have finished running.<br><br></li>
<li><strong>Action canceling.</strong> The <strong>client</strong> may send a
<strong>request</strong> to cancel the current and/or all pending actions,
however some actions cannot be canceled once they have been started. If
actions are still pending, then can always be canceled.<br></li>
</ul>
<h3>Example: Performing a scan disk</h3>
<p>Open the action interface:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Action&gt;</samp><br>
<samp> &lt;OpenSession/&gt;</samp><br>
<samp> &lt;/Action&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>Response:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Action Handle=&quot;808AE63AD3EB002A&quot;
ActionStatus=&quot;Successful&quot;&gt;</samp><br>
<samp> &lt;ActionProfile ActionType=&quot;OpenSession&quot;&gt;</samp><br>
<samp> &lt;/ActionProfile&gt;</samp><br>
<samp> &lt;/Action&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>Request the scan disk:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Action Handle=&quot;808AE63AD3EB002A&quot;&gt;</samp><br>
<samp> &lt;ScanDisk&gt;</samp><br>
<samp> &lt;Disk Name=&quot;DD002&quot;/&gt;</samp><br>
<samp> &lt;/ScanDisk&gt;</samp><br>
<samp> &lt;/Action&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>Response:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Action&gt;</samp><br>
<samp> &lt;ActionProfile ActionType=&quot;ScanDisk&quot; ActionID=&quot;0&quot;&gt;</samp><br>
<samp> &lt;/ActionProfile&gt;</samp><br>
<samp> &lt;/Action&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>Check the Status:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Status Handle=&quot;808AE63AD3EB002A&quot;&gt;</samp><br>
<samp> &lt;ActionProfile ActionType=&quot;ScanDisk&quot; ActionID=&quot;0&quot;&gt;</samp><br>
<samp> &lt;/ActionProfile&gt;</samp><br>
<samp> &lt;/Status&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>Response:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Status&gt;</samp><br>
<samp> &lt;ActionProfile ActionType=&quot;ScanDisk&quot;</samp><br>
<samp> ActionID=&quot;0&quot;</samp><br>
<samp> PercentDone=&quot;24&quot;</samp><br>
<samp> ActionState=&quot;Running&quot;&gt;</samp><br>
<samp> &lt;/ActionProfile&gt;</samp><br>
<samp> &lt;/Status&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>Close the action interface:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Action Handle=&quot;808AE63AD3EB002A&quot;&gt;</samp><br>
<samp> &lt;CloseSession/&gt;</samp><br>
<samp> &lt;/Action&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>Response:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Action ActionStatus=&quot;Successful&quot;&gt;</samp><br>
<samp> &lt;ActionProfile ActionType=&quot;CloseSession&quot;&gt;</samp><br>
<samp> &lt;/ActionProfile&gt;</samp><br>
<samp> &lt;/Action&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp><br>
</p>
<br>
<h2><a name="infint">The Information interface</a></h2>
<p>Information requests may be requested regardless of the current state of the
action interface. The information returned will be the most up to date
information possible. The information interface may also be used to find out
about proposed configuration changes. If a <strong>script</strong> contains an
Info <strong>request</strong> after an Action request, the Info
<strong>request</strong> will be run after the actions are verified, but before
the actions have been run. The <strong>system</strong> state shown by this
info <strong>request</strong> will not be affected by the requested actions
until these actions have completed.</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Info&gt;</samp><br>
<samp> &lt;IOPInfo Format=&quot;All&quot;&gt;</samp><br>
<samp> &lt;IOPFilter Value=&quot;All&quot;/&gt;</samp><br>
<samp> &lt;/IOPInfo&gt;</samp><br>
<samp> &lt;/Info&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>Response:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Info&gt;</samp><br>
<samp> &lt;IOPInfo&gt;</samp><br>
<samp> &lt;IOP</samp><br>
<samp> Number=&quot;1&quot;</samp><br>
<samp> Name=&quot;CMB01&quot;</samp><br>
<samp> NumberOfControllers=&quot;6&quot;</samp><br>
<samp> NumberOfDisks=&quot;4&quot;</samp><br>
<samp> SerialNumber=&quot;10-5059003&quot;</samp><br>
<samp> &lt;/IOP&gt;</samp><br>
<samp> &lt;/IOPInfo&gt;</samp><br>
<samp> &lt;/Info&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<br>
<h2><a name="statint">The Status interface</a></h2>
<p>The purpose of the status interface is to show the status of action
requests. It is also to be used to keep the action interface open for a
particular client. Status can be checked for all actions, actions owned by the
<strong>client</strong> that have the action interface open, or for an action
specified by the actionID. If an action fails when it is running, the status
interface can be used to retrieve error information about the failure. For
long running actions, the status may also return the percent done of the action
and the stage of the action. Actions are not required to provide the percent
done or the stage. If the stage is provided, the action description will
identify the possible values for this attribute. Up to 512 ActionProfiles are
stored on the system, however this data is lost when the
<strong>system</strong> is IPLed.</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Status Handle=&quot;80A186238C9B0061&quot;&gt;</samp><br>
<samp> &lt;/Status&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>Response:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Status&gt;</samp><br>
<samp> &lt;ActionProfile&gt;</samp><br>
<samp> ActionType=&quot;ScanDisk&quot;&gt;</samp><br>
<samp> ActionID=&quot;1&quot;&gt;</samp><br>
<samp> PercentDone=&quot;24&quot;&gt;</samp><br>
<samp> ActionState=&quot;Running&quot;&gt;</samp><br>
<samp> &lt;/ActionProfile&gt;</samp><br>
<samp> &lt;/Status&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<br>
<h2><a name="msgs">Messages</a></h2>
<p>Messages are used to return information about a request. They may occur
anywhere in the <strong>response</strong> and are the primary means for the
system to communicate errors, warnings and information about an action.
Messages will always contain a message ID, and may contain one or more pieces
of data to further explain the message. For example, if an &lt;OpenSession&gt;
tag is sent while the interface is already open, the <strong>response</strong>
will be the following:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Action&gt;</samp><br>
<samp> &lt;OpenSession/&gt;</samp><br>
<samp> &lt;/Action&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp></p>
<p>Response:</p>
<p><samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;DMConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp> &lt;Action ActionStatus=&quot;Failed&quot;&gt;</samp><br>
<samp> &lt;Message</samp><br>
<samp> MessageID=&quot;2&quot;</samp><br>
<samp> MessageType=&quot;Error&quot;&gt;</samp><br>
<samp> &lt;MessageData</samp><br>
<samp> Type=&quot;SessionType&quot;</samp><br>
<samp> Value=&quot;GUI&quot;/&gt;</samp><br>
<samp> &lt;/Message&gt;</samp><br>
<samp> &lt;/Action&gt;</samp><br>
<samp>&lt;/DMConfigurationScript&gt;</samp><br>
</p>
<br>
<h2><a name="valxml">Validation of the XML</a></h2>
<p>When a <strong>script</strong> is received by the system, the syntax and
data are validated. If there are any errors, the <strong>script</strong> will
not be processed. It is advised to validate the <strong>request</strong>
against the Document Type Definition (DTD) before sending the
<strong>request</strong> as syntax errors will be rejected without any
information about where the error occurred. Data errors will be rejected with
a message that identifies the type of error and the data in error. Errors that
occur during the running of an action may be identified through the status
interface.<br>
</p>
<h2><a name="version">Version</a></h2>
<p>The version of the markup language will start at 1 and will be incremented
every time the language is modified. All versions of DMConfigurationScript and
LPARConfigurationScript and any other Hardware Configuration Markup Language
are guaranteed to be upward compatible. Therefore if a client understands
version 2 and the server understands version 3, this is a valid configuration.
However if the <strong>client</strong> only understands version 3 and the
server understands version 2, communications will not be possible. The
<strong>user</strong> interface may be written to work with any version of the
server by conditionally allowing newer actions only for systems that support
these actions. Tags that are added or changed will be identified in the
documentation along with the version in which they changed. To get the version
of the server, the <strong>client</strong> can send an empty
<strong>request</strong> to the server with version 1 specified. The server
will respond back with its version.</p>
<p>Request:<br>
<samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>LPARConfigurationScript DTDVersion=&quot;1&quot;&gt;</samp><br>
<samp>&lt;/LPARConfigurationScript&gt;</samp></p>
<p>Response:<br>
<samp>&lt;?xml version = &quot;1.0&quot; ?&gt;</samp><br>
<samp>&lt;LPARConfigurationScript DTDVersion=&quot;3&quot;&gt;</samp><br>
<samp>&lt;/LPARConfigurationScript&gt;</samp><br>
</p>
<h2><a name="terms">Terminology</a></h2>
<ul>
<li>A <strong>user</strong> may be considered anything that sends an XML
<strong>script</strong> to the iSeries system. A <strong>user</strong> and a
<strong>client</strong> are synonymous.</li>
<li>A <strong>system</strong>differs between Disk Management and LPAR. For
Disk Management, every logical <strong>system</strong> is a
<strong>system</strong>, whereas for LPAR, a <strong>system</strong> is a
physical server.</li>
<li>A <strong>script</strong> is any XML <strong>request</strong> or
<strong>response</strong> enclosed in the <samp>&lt;DMConfigurationScript&gt;
... &lt;/DMConfigurationScript&gt;</samp> tags.</li>
<li>A <strong>request</strong> is one single part of a script. That is, a
script can contain multiple <strong>requests</strong>. For example, a single
script may contain an Informational <strong>request</strong> and multiple
Action requests.</li>
<li>A <strong>response</strong> is the <strong>system</strong> XML
<strong>response</strong> to a single request. Just as a <strong>user</strong>
may send multiple <strong>requests</strong> in a single
<strong>script</strong>, a <strong>system</strong> may return multple
<strong>responses</strong> in a single <strong>script</strong>.</li>
<li>A <strong>session</strong> is created whenever a <strong>user</strong>
requests a <strong>system</strong> configuration change through the Action
interface. (See <a href="#infint">The Information interface</a>.)</li>
</ul>
</body>
</html>