An outgoing XML response closely matches the structure of the incoming request in terms of the commands and objects included, with the addition of a <Response> section for each object and command specified, as well as an overall <Response> section for the request. The <Response> sections provide status and message information as described in Example 12–2. Following is the structure of a response to a basic XML request.
<LDM_interface version="1.0"> <cmd> <action>Place command here</action> <data version="3.0"> <Envelope> <References/> <!-- Note a <Section> section can be here instead of <Content> --> <Content xsi:type="ovf:VirtualSystem_Type" id="Domain name"> <Section xsi:type="ovf:ResourceAllocationSection_type"> <Item> <rasd:OtherResourceType> LDom Resource Type </rasd:OtherResourceType> <gprop:GenericProperty key="Property name"> Property Value </gprop:GenericProperty> </Item> </Section> <!-- Note: More <Section> sections can be placed here --> </Content> </Envelope> <response> <status>success or failure</status> <resp_msg>Reason for failure</resp_msg> </response> </data> <!-- Note: More Data sections can be placed here --> <response> <status>success or failure</status> <resp_msg>Reason for failure</resp_msg> </response> </cmd> <!-- Note: More Command sections can be placed here --> <response> <status>success or failure</status> <resp_msg>Reason for failure</resp_msg> </response> </LDM_interface> |
This <response> section, which is the direct child of the <LDM_interface> section, indicates overall success or failure of the entire request. Unless the incoming XML document is malformed, the <response> section includes only a <status> tag. If this response status indicates success, all commands on all objects have succeeded. If this response status is a failure and there is no <resp_msg> tag, then one of the commands included in the original request failed. The <resp_msg> tag is used only to describe some problem with the XML document itself.
The <response> section under the <cmd> section alerts the user to success or failure of that particular command. The <status> tag shows if that command succeeds or fails. As with the overall response, if the command fails, the <response> section includes only a <resp_msg> tag if the contents of the <cmd> section of the request is malformed. Otherwise, the failed status means one of the objects the command ran against caused a failure.
Finally, each <data> section in a <cmd> section also has a <response> section. This shows if the command being run on this particular object passes or fails. If the status of the response is SUCCESS, there is no <resp_msg> tag in the <response> section. If the status is FAILURE, there are one or more <resp_msg> tags in the <response> field, depending on the errors encountered when running the command against that object. Object errors can result from problems found when running the command, or a malformed or unknown object.
In addition to the <response> section, the <data> section can contain other information. This information is in the same format as an incoming <data> field, describing the object that caused a failure. See The <data> Tag. This additional information is especially useful in the following cases:
When a command fails against a particular <data> section but passes for any additional <data> sections
When an empty <data> section is passed into a command and fails for some domains but passes for others