Resource Management Interface Specs Scott Jackson

Draft Initial Release v. 2.0.6 Brett Bode

9 JUN 2003 David Jackson

Scalable Systems Software Resource Management and Accounting Protocol
(SSSRMAP) Message Format

Status of this Memo

> This is a draft form of a specification defining an XML message format
> used between Scalable Systems Software components. It is intended that
> this specification will continue to evolve as these interfaces are
> implemented and thoroughly tested by time and experience.

Abstract

> *This document is a specification describing a message format for the
> interaction of resource management and accounting software components
> developed as part of the Scalable Systems Software Center. The SSSRMAP
> Message Format defines a request-response syntax supporting the query
> and update of extensible objects. The protocol is specified in XML
> Schema Definition. The message elements defined in this specification
> are intended to be framed within the Envelope element defined within
> the SSSRMAP Wire Protocol specification document.*

Table of Contents

[1 Introduction 2](#introduction)

[2 Conventions Used in this Document
2](#conventions-used-in-this-document)

[2.1 Keywords 2](#keywords)

[2.2 XML Case Conventions 2](#xml-case-conventions)

[3 Encoding 3](#encoding)

[3.1 SSSRMAP Message Types 3](#sssrmap-message-types)

[3.1.1 Schema Header and Namespaces 4](#schema-header-and-namespaces)

[3.1.2 The *Envelope* Element 4](#the-envelope-element)

[3.1.3 The *Body* Element 5](#the-body-element)

[3.1.4 The *Request* Element 5](#the-request-element)

[3.1.5 The *Get* Element 6](#the-get-element)

[3.1.6 The *Set* Element 7](#the-set-element)

[3.1.7 The *Where* Element 8](#the-where-element)

[3.1.8 The *Option* Element 9](#the-option-element)

[3.1.9 The *Data* Element 9](#the-data-element)

[3.1.10 The *File* Element 10](#the-file-element)

[3.1.11 The *Count* Element 11](#the-count-element)

[3.1.12 The *Response* Element 12](#the-response-element)

[3.1.13 The *Status* Element 12](#the-status-element)

[3.1.14 The *Code* Element 13](#the-code-element)

[3.1.15 The *Message* Element 13](#the-message-element)

[3.1.16 The *Notify* Element 13](#the-notify-element)

[3.1.17 The *Ack* Element 14](#the-ack-element)

[3.2 Examples 14](#examples)

[3.2.1 Sample Requests 14](#sample-requests)

[3.2.2 Sample Responses 15](#sample-responses)

[3.2.3 Sample Notification 17](#sample-notification)

[3.2.4 Sample Acknowledgement 17](#sample-acknowledgement)

[4 Error Reporting 17](#error-reporting)

[5 Acknowledgements 18](#acknowledgements)

[6 References 18](#references)

# Introduction

> A major objective of the Scalable Systems Software \[SSS\] Center is
> to create a scalable and modular infrastructure for resource
> management on terascale clusters including resource scheduling,
> meta-scheduling, node daemon support, comprehensive usage accounting
> and user interfaces emphasizing portability to terascale vendor
> operating systems. Existing resource management and accounting
> components feature disparate APIs (Application Programming Interfaces)
> requiring various forms of application coding to interact with other
> components.
>
> This document proposes a wire level protocol expressed in an XML
> request-response syntax to be considered as the foundation of a
> standard for communications between and among resource management and
> accounting software components. In this document this standard is
> expressed in two levels of generality. The features of the core
> SSSRMAP protocol common to all resource management and accounting
> components in general are described in the main body of this document.
> The aspects of the syntax specific to individual components are
> described in the Appendix.

# Conventions Used in this Document

## Keywords

The keywords "MUST", "MUST NOT", "REQUIIRED", "SHALL", "SHALL NOT",
"SHOULD", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to
be interpreted as described in RFC2119 \[RFC2119\].

## XML Case Conventions

> In order to enforce a consistent capitalization and naming convention
> across all SSSRMAP specifications "Upper Camel Case" (UCC) and "Lower
> Camel Case" (LCC) Capitalization styles shall be used. UCC style
> capitalizes the first character of each word and compounds the name.
> LCC style capitalizes the first character of each word except the
> first word. \[XML_CONV\]\[FED_XML\]

1.  SSSRMAP XML Schema and XML instance documents SHALL use the
    following conventions:

    -   Element names SHALL be in UCC convention (example:
        \<UpperCamelCaseElement/\>.

    -   Attribute names SHALL be in LCC convention (example:
        \<UpperCamelCaseElement lowerCamelCaseAttribute="Whatever"/\>.

2.  General rules for all names are:

-   Acronyms SHOULD be avoided, but in cases where they are used, the
    capitalization SHALL remain (example: XMLSignature).

-   Underscores (\_), periods (.) and dashes (-) MUST NOT be used
    (example: use JobId instead of JOB.ID, Job_ID or job-id).

# Encoding

> Encoding tells how a message is represented when exchanged. SSSRMAP
> data exchange messages SHALL be defined in terms of XML schema
> \[XML_SCHEMA\].

## SSSRMAP Message Types

> The SSSRMAP protocol provides four general message types: requests,
> responses, notifications and acknowledgements.
>
> When a session is established and the client authenticated, the
> protocol allows two styles of data exchange between the client and
> server. \[XRP\]

1.  Request/Response -- the client sends a "Request" message requesting
    the server to perform the task, the server performs the task and
    returns a "Response" reply. \[XRP\]

2.  Notify/Ack -- the server notifies clients about certain events in
    the system, and receives an "ack" reply as an acknowledgement.
    \[XRP\]

> Both styles are one-to-one synchronous exchanges wherein a single
> message is sent from the client to the server, and a corresponding
> reply is sent from the server to the client.
>
> Any combination and number of these message types may be framed within
> a *Body* and *Envelope* element as an HTTP payload as described in the
> SSSRMAP Wire Protocol document. The four message types are described
> in the next section.

### Schema Header and Namespaces

> The header of the schema definition is as follows:
>
> \<?xml version=\"1.0\" encoding=\"UTF-8\"?\>
>
> \<schema

xmlns="<http://www.w3.org/2001/XMLSchema>"

xmlns:sssrmap="http://www.scidac.org/ScalableSystems/SSSRMAP"

targetNamespace="http://www.scidac.org/ScalableSystems/SSSRMAP"

elementFormDefault=\"qualified\"\>

### The *Envelope* Element

> SSSRMAP messages and replies are encapsulated in the *Envelope*
> element. There are two possibilities for the contents of this element.
> If the contents are unencrypted, this element MUST contain a *Body*
> element and MAY contain a *Signature* element (refer to the section on
> Security). The *Signature* element, if it appears, MUST appear before
> the *Body* element. If the contents are encrypted, this element MUST
> contain exactly one *EncryptedData* element (refer to the section on
> Security). The *Envelope* element MAY contain namespace and other
> xsd-specific information necessary to validate the document against
> the schema. In addition, it MAY have any of the following attributes
> which may serve as processing clues to the parser:

-   *type* -- A message type providing a hint as to the body contents
    such as "Request" or "Notification"

-   *actor* -- The authenticated user sending the message

-   *count* -- A positive integer indicating the number of messages in
    the batch

-   *component* -- A component type such as "QueueManager" or
    "LocalScheduler"

-   *name* -- A component name such as "OpenPBS" or "Maui"

-   *version* -- A component version such as "2.2p12" or "3.2.2"

> Schema Definition:
>
> \<complexType name=\"EnvelopeType\"\>
>
> \<choice minOccurs="1" maxOccurs="1"\>
>
> \<sequence\>
>
> \<element ref=\"sssrmap:Signature\" minOccurs=\"0\" maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:Body\" minOccurs=\"1\" maxOccurs=\"1\"/\>
>
> \</sequence\>
>
> \<element ref="sssrmap:EncryptedData" minOccurs="1" maxOccurs="1"/\>
>
> \</choice\>
>
> \<attribute name=\"type\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"actor\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"count\" type="integer" use=\"optional\"/\>
>
> \<attribute name=\"component\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"name\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"version\" type="string" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Envelope\" type=\"sssrmap:EnvelopeType\"/\>

### The *Body* Element

> SSSRMAP messages and replies are encapsulated in the *Body* element.
> This element MUST either contain one or more *Request*, *Response*,
> *Notify* or *Ack* elements.
>
> Schema Definition:
>
> \<complexType name=\"BodyType\"\>

\<choice minOccurs=\"1\" maxOccurs=\"unbounded\"\>

> \<element ref=\"sssrmap:Request\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\> \<element ref=\"sssrmap:Response\"
> minOccurs=\"0\" maxOccurs=\"unbounded\"/\>
>
> \<element ref=\"sssrmap:Notify\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<element ref=\"sssrmap:Ack\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<any minOccurs=\"0\" maxOccurs=\"unbounded\" namespace=\"##other\"/\>
>
> \</choice\>
>
> \</complexType\>
>
> \<element name=\"Body\" type=\"sssrmap:BodyType\"/\>

### The *Request* Element

> The *Request* element specifies an individual request. Depending on
> context, it MAY contain one or more *Get* elements or one or more
> *Set* elements as well as a *Count* element and any number of *Where*
> or *Data* elements.
>
> It MUST have both an *object* and *action* attribute and MAY have an
> *id* attribute.

-   *object* -- specifies the object class to be acted upon such as
    "job" or "node"

-   *action* -- specifies the action to be performed on the object such
    as "create", "query", "modify" or "delete"

-   *id* \-- uniquely maps the request to the appropriate response

> Schema Definition:
>
> \<complexType name=\"RequestType\"\>
>
> \<choice minOccurs=\"0\" maxOccurs=\"unbounded\"\>
>
> \<choice minOccurs=\"0\" maxOccurs=\"1\"\>
>
> \<element ref=\"sssrmap:Get\" minOccurs=\"1\"
> maxOccurs=\"unbounded\"/\>
>
> \<element ref=\"sssrmap:Set\" minOccurs=\"1\"
> maxOccurs=\"unbounded\"/\>
>
> \</choice\>
>
> \<element ref=\"sssrmap:Where\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<element ref=\"sssrmap:Data\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<element ref=\"sssrmap:Count\" minOccurs=\"0\" maxOccurs=\"1\"/\>
>
> \<any namespace="##other" minOccurs=\"0\" maxOccurs=\"unbounded\"/\>
>
> \</choice\>
>
> \<attribute name=\"object\" type=\"string\" use=\"required\"/\>
>
> \<attribute name=\"action\" type=\"string\" use=\"required\"/\>
>
> \<attribute name=\"id\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Request\" type=\"sssrmap:RequestType\"/\>

### The *Get* Element

> The *Get* element is used to indicate the data fields to be returned
> in a query. *Get* is typically used within requests with
> *action*="query". Multiple *Get* elements cause the fields to be
> returned in the order specified. If no *Get* elements are specified,
> the query will return a default set of fields.
>
> The valid attributes are:

-   *name* -- the name of the data field to be returned

-   *op* -- the operator to be used to aggregate or perform an operation
    on the returned values.

    -   An *op* attribute of "sort" specifies an ascending sort
        operation

    -   An *op* attribute of "tros" specifies a descending sort
        operation

    -   An *op* attribute of "sum" returns the sum (only valid for
        numeric values)

    -   An *op* attribute of "max" returns the maximum value

    -   An *op* attribute of "min" returns the minimum value

    -   An *op* attribute of "count" returns the number of values

    -   An *op* attribute of "groupby" signifies that aggregates are
        grouped by this field

-   *units* -- the units in which to return the value (if applicable)

> Schema Definition:
>
> \<complexType name=\"GetType\"\>
>
> \<attribute name=\"name\" type="string" use=\"required\"/\>
>
> \<attribute name=\"units\" type="string" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Get\" type=\"sssrmap:GetType\"/\>

### The *Set* Element

> The *Set* element is used to specify the object data fields to be
> assigned values. *Set* is typically used within requests with
> *action*="create" or *action*="modify". The use of *Get* or *Set*
> elements within a request are mutually exclusive.

The valid attributes are:

-   *name* -- the name of the field being assigned a value

-   *value* -- the new value for the field being changed

-   *op* -- the operator to be used in assigning a new value to the
    name. If an *op* attribute is not specified and a value is
    specified, the specified value will be assigned to the named field
    ("assign").

    -   An *op* attribute of "assign" assigns value to the named field

    -   An *op* attribute of "inc" increments the named field by the
        value

    -   An *op* attribute of "dec" decrements the named field by the
        value

-   *units* -- the units corresponding to the value being set

A *Set* element without a *value* may be used as an assertion flag.

> Schema Definition:
>
> \<complexType name=\"SetType\"\>
>
> \<attribute name=\"name\" type="string" use=\"required\"/\>
>
> \<attribute name=\"value\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"units\" type="string" use=\"optional\"/\>

\</complexType\>

> \<element name=\"Set\" type=\"sssrmap:SetType\"/\>

### The *Where* Element

> A *Request* element may contain one or more *Where* elements that
> specify the search conditions for which objects the action is to be
> performed on or supply constraints or options to the request.
>
> Only a *name* attribute is required. All other fields are optional.

-   *name* -- the name of the data field to be tested

-   *value* -- the value against which the objects data value is tested

-   *op* -- the operator to be used to test the name against the value.
    If an *op* attribute is not specified and a value is specified, the
    field will be tested whether it is equal to the value ("eq").

    -   An *op* attribute of "eq" specifies an equality comparison

    -   An *op* attribute of "lt" specifies a "less than" comparison

    -   An *op* attribute of "gt" specifies a "greater than" comparison

    -   An *op* attribute of "le" specifies a "less than or equal to"
        test

    -   An *op* attribute of "ge" specifies a "greater than or equal to"
        test

    -   An *op* attribute of "ne" specifies a "not equal to" test

    -   An *op* attribute of "like" specifies a regular expression
        matching comparison

-   *conj* \-- indicates whether this test is to be anded or ored with
    the immediately preceding where condition

    -   A *conj* attribute of "and" specifies an "and" conjunction

    -   A *conj* attribute of "or" specifies an "or" condition

    -   A *conj* attribute of "andnot" specifies an "and not"
        conjunction

    -   A *conj* attribute of "ornot" specifies an "or not" condition

-   *group --* indicates an increase or decrease of parentheses grouping
    depth

    -   A positive number indicates the number of left parentheses to
        precede the condition, i.e. *group*="2" represents
        "((condition".

    -   A negative number indicates the number of right parentheses to
        follow the condition, i.e. *group*="-2" represents
        "condition))".

-   *units* -- indicates the units to be used in the value comparison

> Schema Definition:
>
> \<complexType name=\"WhereType\"\>
>
> \<attribute name=\"name\" type="string" use="required"/\>
>
> \<attribute name=\"value\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"op\" type=\"sssrmap:OperatorType\"
> use=\"optional\"/\>
>
> \<attribute name=\"conj\" type=\"sssrmap:ConjunctionType\"
> use=\"optional\"/\>
>
> \<attribute name=\"group\" type=\"integer\" use=\"optional\"/\>
>
> \<attribute name=\"units\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Where\" type=\"sssrmap:WhereType\"/\>

### The *Option* Element

> The *Option* element is used to indicate processing options for the
> command. An option might be used to indicate that command usage or
> special formatting is desired, or that the command is to be invoked
> with particular options.

The valid attributes are:

-   *name* -- the name of the field being assigned a value

-   *value* -- the new value for the field being changed

-   *op* -- the operator to be used to disassert the option

    -   An *op* attribute of "not" specifies that the option is not
        asserted

-   *conj* \-- indicates whether this test is to be anded or ored with
    the immediately preceding where condition

    -   A *conj* attribute of "and" specifies an "and" conjunction

    -   A *conj* attribute of "or" specifies an "or" condition

    -   A *conj* attribute of "andnot" specifies an "and not"
        conjunction

    -   A *conj* attribute of "ornot" specifies an "or not" condition

An *Option* element without a *value* may be used as an assertion flag.

> Schema Definition:
>
> \<complexType name=\"OptionType\"\>

\<attribute name=\"name\" type="string" use=\"required\"/\>

> \<attribute name=\"value\" type="string" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Option\" type=\"sssrmap:OptionType\"/\>

### The *Data* Element

> A *Request* or *Response* element may have one or more *Data* elements
> that allow the supplying of context-specific data. A request might
> pass in a structured object via a *Data* element to be acted upon.
> Typically a query will result in a response with the data encapsulated
> within a *Data* element.
>
> The following attributes are optional:

-   *name* -- object name describing the contents of the data

-   *type* -- describing the form in which the data is represented

    -   A *type* attribute of "xml" indicates the data has internal xml
        structure and can be recursively parsed by an XML parser

    -   A *type* attribute of "binary" indicates the data is an opaque
        dataset consisting of binary data

    -   A *type* attribute of "string" indicates the data is an ASCII
        string

    -   A *type* attribute of "int" indicates the data is an integer

    -   A type attribute of "text" indicates the data is in formatted
        human-readable text

    -   A type attribute of "html" indicates the data is represented in
        HTML

Schema Definition:

> \<complexType name=\"DataType\"\>
>
> \<sequence\>
>
> \<any namespace=\"##any\" processContents=\"lax\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \</sequence\>
>
> \<attribute name=\"name\" type="string" use=\"optional\"/\>
>
> \<attribute ref=\"sssrmap:Type\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Data\" type=\"sssrmap:DataType\"/\>

### The *File* Element

> A *Request* or *Response* element may have one or more *File* elements
> of type String that allow the inclusion of files. The files may be
> either text or binary and may be referenced by objects inside the Data
> element. A file may be compressed using the gzip algorithm \[ZIP\]. A
> binary file or a compressed file must be base64 encoded as defined in
> XML Digital Signatures ("http://www.w3.org/2000/09/xmldsig#base64").
> Metadata describing the modes and properties of the resulting file are
> passed as parameters. The text or base64 encoded file data forms the
> string content of the *File* element.
>
> The following attributes are optional:

-   *id* \-- specifies an identifier that allows the file to be
    referenced from within another object. If more than one *File*
    elements are specified, this attribute is REQUIRED in each of them.

-   *name \--* specifies the name to give the file upon creation on the
    target system. This can be an absolute or relative pathname
    (relative to the InitialWorkingDirectory).

-   *owner* -- indicates what owner the file should be changed to. By
    default it will be changed to the UserId that the authenticated
    actor maps to on the target system. Note that this function should
    succeed only if the requestor has the privileges to do so (i.e.
    authenticated as root).

-   *group* -- indicates what group the file should be changed to. By
    default it will be set to the primary groupid of the UserId that the
    authenticated actor maps to on the target system. Note that this
    function should succeed only if the requestor has the proper
    privileges.

-   *mode* -- indicates the permissions the file should possess. By
    default it will be set according to the default umask for the UserId
    that the authenticated actor maps to on the target system. Note that
    this function should not set permissions for the file that exceed
    the privileges for the actor. These permissions can be specified
    using either an octal number or symbolic operations (as accepted by
    the GNU chmod(1) command).

-   *compressed* -- indicates whether the file has been compressed

    -   A *compressed* attribute of "true" indicates the file has been
        compressed.

    -   A *compressed* attribute of "false" indicates the file has not
        been compressed. This is the default.

-   encoded -- indicates whether the file has been base64 encoded

    -   An *encoded* attribute of "true" indicates the file has been
        compressed.

    -   An *encoded* attribute of "false" indicates the file has not
        been encoded. This is the default.

Schema Definition:

> \<complexType name=\"FileType\"\>
>
> \<sequence\>
>
> \<any namespace=\"##any\" processContents=\"lax\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \</sequence\>
>
> \<attribute name=\"name\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"owner\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"group\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"mode\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"compressed\" type="boolean" use=\"optional\"/\>
>
> \<attribute name=\"encoded\" type=\"boolean\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"File\" type=\"sssrmap:FileType\"/\>

### The *Count* Element

> A single *Count* element may be included within a *Request* or
> *Response* and is context-specific. This can be used to represent the
> number of objects acted upon.
>
> Schema Definition:
>
> \<element name=\"Count\" type=\"positiveInteger\"/\>

### The *Response* Element

> The *Response* element specifies an individual response. It MUST
> contain *Status* and *Code* elements. It MAY also contain *Message*,
> *Count* and any number of *Data* elements.
>
> It MAY have an *object* and *action* attribute as well as an *id*
> attribute.

-   *object* -- specifies the object class to be acted upon such as
    "job" or "node"

-   *action* -- specifies the action to be performed on the object such
    as "create", "query", "modify" or "delete"

-   *id* \-- uniquely maps the response to the corresponding request

> Schema Definition:
>
> \<complexType name=\"ResponseType\"\>
>
> \<choice minOccurs=\"0\" maxOccurs=\"unbounded\"\>
>
> \<element ref=\"sssrmap:Status\" minOccurs=\"1\" maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:Code\" minOccurs=\"1\" maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:Message\" minOccurs=\"0\" maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:Count\" minOccurs=\"0\" maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:Data\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<any minOccurs=\"0\" maxOccurs=\"unbounded\" namespace=\"##other\"/\>
>
> \</choice\>
>
> \<attribute name=\"object\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"action\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"id\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Response\" type=\"sssrmap:ResponseType\"/\>

### The *Status* Element

> A *Response* element must contain a single *Status* element that
> indicates whether the reply represents a success or a failure. The
> *Status* element MUST have a value of "Success" or "Failure".
>
> Schema Definition:
>
> \<simpleType name=\"SuccessType\"\>
>
> \<restriction base=\"string\"\>
>
> \<enumeration value=\"Success\"/\>
>
> \<enumeration value=\"Failure\"/\>
>
> \</restriction\>
>
> \</simpleType\>
>
> \<element name=\"Status\" type=\"sssrmap:StatusType\"/\>

### The *Code* Element

> A *Response* element must contain a single *Code* element that
> specifies the 3-digit status code for the response.

Schema Definition:

\<simpleType name=\"CodeType\"\>

\<restriction base=\"string\"\>

\<pattern value=\"\[0-9\]{3}\"/\>

\</restriction\>

\</simpleType\>

\<element name=\"Code\" type=\"sssrmap:CodeType\"/\>

### The *Message* Element

> A *Response* element may contain a single *Message* element that is
> context specific to the success or failure response. The message
> should be an error message if status is false. If present for a
> successful response, it may be used as a human readable message for a
> user interface.
>
> Schema Definition:
>
> \<element name=\"Message\" type=\"string\"/\>

### The *Notify* Element

> The *Notify* element may have one or more *Data* elements that carry
> the context-specific data with the event notification.
>
> It must have a name attribute while the others are optional:

-   *name* -- the name of the event that was triggered

-   *value* -- the value for the object that was changed

-   *id* -- uniquely maps the notification to its acknowledgement

> Schema Definition:
>
> \<complexType name=\"NotifyType\"\>
>
> \<choice minOccurs=\"0\" maxOccurs=\"unbounded\"\>
>
> \<element ref=\"sssrmap:Data\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<any namespace=\"##other\" minOccurs=\"0\" maxOccurs=\"unbounded\"/\>
>
> \</choice\>
>
> \<attribute name=\"name\" type=\"string\" use=\"required\"/\>
>
> \<attribute name=\"value\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"id\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Notify\" type=\"sssrmap:NotifyType\"/\>

### The *Ack* Element

> The Ack element may have a name attribute:

-   *name* -- the name of the event that was triggered

-   *id* -- uniquely maps the acknowledgement to the corresponding
    notification

> Schema Definition:
>
> \<complexType name=\"AckType\"\>
>
> \<attribute name=\"name\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"id\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Ack\" type=\"sssrmap:AckType\"/\>

## Examples

### Sample Requests

> Requesting a list of nodes with a certain configured memory threshold
> (batch format):
>
> \<Envelope component="NodeMonitor" count="1"\>
>
> \<Body\>
>
> \<Request object="Node" action="Query" id="1"\>
>
> \<Get name="Name" /\>
>
> \<Get name="ConfiguredMemory" /\>
>
> \<Where name="ConfiguredMemory" op="ge" unit="MB" value="512"/\>
>
> \</Request\>
>
> \</Body\>
>
> \</Envelope\>
>
> Activating a couple of users:
>
> \<Envelope actor="root"\>
>
> \<Body\>
>
> \<Request object="User" action="Modify"\>
>
> \<Set name="Active" value="true"/\>
>
> \<Where name="Name" value="scott"/\>
>
> \<Where name="Name" value="brett" conj="or"/\>
>
> \</Request\>

\</Body\>

\</Envelope\>

> Submitting a simple job:

\<Envelope\>

> \<Body\>
>
> \<Request object="Job" action="Submit"\>
>
> \<Data type="xml"\>
>
> \<Job\>
>
> \<User\>xdp\</User\>
>
> \<Account\>youraccount\</Account\>
>
> \<Command\>myprogram\</Command\>
>
> \<Cwd\>/usr/home/scl/xdp\</Cwd\>
>
> \<RequestedNodes\>4\</RequestedNodes\>
>
> \<RequestedWCTime\>100\</RequestedWCTime\>
>
> \</Job\>
>
> \</Data\>
>
> \</Body\>
>
> \</Request\>

\</Envelope\>

### Sample Responses

> A response to the available memory nodes query (batch format)
>
> \<Envelope count="1"\>
>
> \<Body\>
>
> \<Response object="node" action="query" id="1"\>
>
> \<Status\>true\</Status\>
>
> \<Code\>000\</Code\>
>
> \<Count\>2\</Count\>
>
> \<Data name="NodeList" type="xml"\>
>
> \<Node\>
>
> \<Name\>fr01n01\</Name\>
>
> \<ConfiguredMemory\>512\</ConfiguredMemory\>
>
> \</Node\>
>
> \<Node\>
>
> \<Name\>fr12n04\</Name\>
>
> \<ConfiguredMemory\>1024\</ConfiguredMemory\>
>
> \</Node\>
>
> \</Data\>
>
> \</Response\>

\</Body\>

\</Envelope\>

Two users successfully activated

\<Envelope\>

\<Body\>

> \<Response\>
>
> \<Status\>true\</Status\>
>
> \<Code\>000\</Code\>
>
> \<Count\>2\</Count\>
>
> \<Message\>Two users were successfully modified\</Message\>
>
> \</Response\>

\</Body\>

> \</Envelope\>
>
> A failed job submission:
>
> \<Envelope\>
>
> \<Body\>
>
> \<Response\>
>
> \<Status\>false\</Status\>
>
> \<Code\>711\</Code\>

\<Message\>Invalid account specified. The job was not
submitted.\</Message\>

> \</Response\>

\</Body\>

\</Envelope\>

### Sample Notification

> A change in available memory triggers a notification:

\<Envelope\>

\<Body\>

> \<Notify name="AvailableMemory" value="952" id="47327"/\>

\</Body\>

\</Envelope\>

### Sample Acknowledgement

> An event subscriber acknowledges receipt of the notification
>
> \<Envelope\>
>
> \<Body\>
>
> \<Ack id="47327"/\>

\</Body\>

\</Envelope\>

# Error Reporting

SSSRMAP requests will return a status and a 3-digit response code to
signify success or failure conditions. When a *request* is successful, a
corresponding *response* is returned with the *status* element set to
true and the *code* element set to "000". When a *request* results in an
error detected by the server, a *response* is returned with the *status*
element set to false and a 3-digit error code in the *code* element. An
optional human-readable *message* may also be include in a failure
response providing context-specific detail about the failure. The
default message language is US English. (The status flag makes it easy
to signal success or failure and allows the receiving peer some freedom
in the amount of parsing it wants to do on failure \[BXXP\]).

Category Code Response Message in US English

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Success 000 Request completed successfully

Unknown Failure 999 Request failed

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

1xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Protocol Syntax 2xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Object Management 3xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Authentication Error 4xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Connection Problem 5xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Server Side Failure 6xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Client Side Failure 7xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Business Logic 8xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

# Acknowledgements

# References

\[RFC2119\] S. Bradner, "Key Words for Use in RFCs to Indicate
Requirement Levels", [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt),
March 1997.

\[BEEP\] M. Rose, "The Blocks Extensible Exchange Protocol Core", [RFC
3080](http://www.ietf.org/rfc/rfc3080.txt), March 2001.

\[HMAC\] H. Krawczyk, M. Bellare, R. Canetti, "HMAC, Keyed-Hashing for
Message Authentication", [RFC
2104](http://www.ietf.org/rfc/rfc2104.txt), February 1997.

\[SHA-1\] U.S. Department of Commerce/National Institute of Standards
and Technology, "[Secure Hash
Standard](http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.txt)",
FIPS PUB 180-1.

\[SSS\] "Scalable Systems Software",
<http://www.scidac.org/ScalableSystems>

\[HTTP\] "Hypertext Transfer Protocol -- HTTP/1.1", [RFC
2616](http://www.w3.org/Protocols/rfc2616/rfc2616.txt), June 1999.

\[XML_CONV\] "[I-X and \<I-N-CA\> XML
Conventions](http://www.aiai.ed.uk/project/ix/inca/xml-conventions.html)".

\[FED_XML\] "[U.S. Federal XML
Guidelines](http://www.xml.com/pub/a/2002/02/06/fedguidelines.html)".

\[RFC3117\] M. Rose, "On the Design of Application Protocols",
[Informational RFC 3117](http://www.faqs.org/rfcs/rfc3117.html),
November 2001.

\[XML_DSIG\] D. Eastlake, J. Reagle Jr., D. Solo, "[XML Signature Syntax
and Processing](http://www.w3.org/TR/xmldsig-core/)", W3C
Recommendation, 12 February 2002.

\[XML_ENC\] T. Imamura, B. Dillaway, E. Smon, "[XML Encryption Syntax
and Processing](http://www.w3.org/TR/xmlenc-core/)", W3C Candidate
Recommendation, 4 March 2002.

\[XRP\] E. Brunner-Williams, A. Damaraju, N. Zhang, "[Extensible
Registry Protocol
(XRP)",](http://www.icann.org/tlds/agreements/biz/draft-brunner-xrp-00.txt)
Internet Draft, expired August 2001.

\[XML\] Bray, T., et al, "[Extensible Markup Language (XML) 1.0 (Second
Edition](http://www.w3.org/TR/2000/REC-xml-20001006))", 6 October 2000.

\[XML_SCHEMA\] D. Beech, M. Maloney, N. Mendelshohn, "[XML Schema Part
1: Structures Working
Draft",](http://www.w3.org/TR/2000/WD-xmlschema-1-20000407) April 2000.

\[ZIP\] J. Gailly, M. Adler, "The gzip home page",
<http://www.gzip.org/>