Introduction to using Hardware Configuration Markup Languages

Logical Partitions and Disk Management
Processing order
The Action interface
The Information interface
The Status interface
Messages
Validation of the XML
Version
Terminology

Logical Partitions and Disk Management

Logical Partition Markup Language (LPML) is defined as LPARConfigurationScript. Disk Management Markup Language (DMML) is defined as DMConfigurationScript.

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.

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 <Info>, <Status>, and <Action> respectively. A single request or response may consist of one or more of these types in no particular order. The format for all data sent should have this basic structure:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Action>
<!-- Requests to perform a configuration change go here -->
</Action>

<Info>
<!-- Requests for information about the current configuration go here -->
</Info>

<Status>
<!-- Requests for information about the status of a configuration
change request goes here -->
</Status>

</DMConfigurationScript>

The format for data returned may look like:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">

<Action>
<!-- will contain ActionProfile with request results -->
</Action>

<Info>
<!-- will contain Information Requested -->
</Info>

<Status>
<!-- will contain Status information requested -->
</Status>

</DMConfigurationScript>

Processing order

In general, tags are processed in the order in which they are listed in the script. Thus, a script may include an Status request (a), followed by an Info request (b), followed by another Status request (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 The Action interface.)

The Action interface

Any request for a configuration change is requested as an action. For LPAR actions, the user must explicitely send an <CommitActions> request in order to commit any previously requested actions. If a <CloseSession> 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.

• The <OpenSession> action tag. To avoid multiple users making conflicting changes to an system, only one user at a time may have the action interface open on a system. To open the interface, the <OpenSession> 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 user until one of the following conditions occurs:
• • The user issues a <CloseSession> action request.
    
  • A severe error occurs on the system or the system is restarted. In either case, the action interface will be closed.
    
  • The user does not send any request 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 user sends a status request containing the handle or the user requests additional actions. One way to guarantee the session remains open is to start a thread on the user system that sends a status request containing the handle every 3 minutes. As long as this thread does not end, the session will remain open.
    

  The status of an action can be one of the following:

  • Pending: The action has been submitted and validated, but has not started running yet.
  • Running: The action is currently running. Only one action may be running at a time.
  • Paused: The action is waiting for feedback from the user.
  • Successful: The action completed successfully.
  • Failed: The action completed unsuccessfully.
  • Purged: The action was not run because a preceding action was canceled or failed.
  • Canceled: The action was canceled by the user.
  
  
• The <CloseSession> action tag. To close the action interface, use the <CloseSession> 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 client failure, and not as a standard exit mechanism.
  
  
• Paused processing. When an action is running, there may be warnings or other information that needs to be provided to the user before the action can complete. This will result in the action pausing and waiting for the user to respond. By checking the status of the action, the client 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 client then has the choice to continue processing the action <ContinueAction>, cancel the action <CancelAction>, or close the action interface <CloseSession>.
  
  
• Processing order. 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 script have completed or have been canceled. Actions will not be processed until all action requests in the script have been verified and any Status or Info requests have been processed. The response from each action request is an action profile <ActionProfile>. 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 script 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.
  
  
• Errors. If an action fails for any reason, all subsequent action requests will not be attempted. For example, if the user requests 5 actions within one script, and the 3rd action does not complete, the 4th and 5th will not be attempted. If the client wants to run these two actions after the failure, the 4th and 5th must be re-requested in a new script.
  
  
• Action stacking. The client may send a script 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 <CancelAction> request, which may be processed while other actions are running. As mentioned above, the <CloseSession> tag may also be processed while an action is running, however it will have no effect until all enqueued actions have finished running.
  
  
• Action canceling. The client may send a request 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.
  

Example: Performing a scan disk

Open the action interface:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Action>
<OpenSession/>
</Action>
</DMConfigurationScript>

Response:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Action Handle="808AE63AD3EB002A" ActionStatus="Successful">
<ActionProfile ActionType="OpenSession">
</ActionProfile>
</Action>
</DMConfigurationScript>

Request the scan disk:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Action Handle="808AE63AD3EB002A">
<ScanDisk>
<Disk Name="DD002"/>
</ScanDisk>
</Action>
</DMConfigurationScript>

Response:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Action>
<ActionProfile ActionType="ScanDisk" ActionID="0">
</ActionProfile>
</Action>
</DMConfigurationScript>

Check the Status:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Status Handle="808AE63AD3EB002A">
<ActionProfile ActionType="ScanDisk" ActionID="0">
</ActionProfile>
</Status>
</DMConfigurationScript>

Response:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Status>
<ActionProfile ActionType="ScanDisk"
ActionID="0"
PercentDone="24"
ActionState="Running">
</ActionProfile>
</Status>
</DMConfigurationScript>

Close the action interface:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Action Handle="808AE63AD3EB002A">
<CloseSession/>
</Action>
</DMConfigurationScript>

Response:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Action ActionStatus="Successful">
<ActionProfile ActionType="CloseSession">
</ActionProfile>
</Action>
</DMConfigurationScript>

The Information interface

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 script contains an Info request after an Action request, the Info request will be run after the actions are verified, but before the actions have been run. The system state shown by this info request will not be affected by the requested actions until these actions have completed.

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Info>
<IOPInfo Format="All">
<IOPFilter Value="All"/>
</IOPInfo>
</Info>
</DMConfigurationScript>

Response:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Info>
<IOPInfo>
<IOP
Number="1"
Name="CMB01"
NumberOfControllers="6"
NumberOfDisks="4"
SerialNumber="10-5059003"
</IOP>
</IOPInfo>
</Info>
</DMConfigurationScript>

The Status interface

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 client 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 system is IPLed.

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Status Handle="80A186238C9B0061">
</Status>
</DMConfigurationScript>

Response:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Status>
<ActionProfile>
ActionType="ScanDisk">
ActionID="1">
PercentDone="24">
ActionState="Running">
</ActionProfile>
</Status>
</DMConfigurationScript>

Messages

Messages are used to return information about a request. They may occur anywhere in the response 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 <OpenSession> tag is sent while the interface is already open, the response will be the following:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Action>
<OpenSession/>
</Action>
</DMConfigurationScript>

Response:

<?xml version = "1.0" ?>
<DMConfigurationScript DTDVersion="1">
<Action ActionStatus="Failed">
<Message
MessageID="2"
MessageType="Error">
<MessageData
Type="SessionType"
Value="GUI"/>
</Message>
</Action>
</DMConfigurationScript>

Validation of the XML

When a script is received by the system, the syntax and data are validated. If there are any errors, the script will not be processed. It is advised to validate the request against the Document Type Definition (DTD) before sending the request 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.

Version

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 client only understands version 3 and the server understands version 2, communications will not be possible. The user 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 client can send an empty request to the server with version 1 specified. The server will respond back with its version.

Request:
<?xml version = "1.0" ?>
LPARConfigurationScript DTDVersion="1">
</LPARConfigurationScript>

Response:
<?xml version = "1.0" ?>
<LPARConfigurationScript DTDVersion="3">
</LPARConfigurationScript>

Terminology

• A user may be considered anything that sends an XML script to the iSeries system. A user and a client are synonymous.
• A systemdiffers between Disk Management and LPAR. For Disk Management, every logical system is a system, whereas for LPAR, a system is a physical server.
• A script is any XML request or response enclosed in the <DMConfigurationScript> ... </DMConfigurationScript> tags.
• A request is one single part of a script. That is, a script can contain multiple requests. For example, a single script may contain an Informational request and multiple Action requests.
• A response is the system XML response to a single request. Just as a user may send multiple requests in a single script, a system may return multple responses in a single script.
• A session is created whenever a user requests a system configuration change through the Action interface. (See The Information interface.)